openfda-database

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

openFDA Search and Query

openFDA 搜索与查询

Prerequisites

前提条件

uv
: Read the
```
uv
```
skill and follow its Setup instructions to ensure
```
uv
```
is installed and on PATH.
User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://open.fda.gov/apis/ and https://open.fda.gov/license, then (2) create the file recording the notification text and timestamp.
.env
file: Make sure the
```
.env
```
file exists in your home directory. Create one if it does not exist.
FDA_API_KEY
(optional but recommended): Raises the daily request limit from 1,000 to 120,000. The skill works without it, but an agent can easily exhaust the keyless limit in a single session. The user can register for a free key at https://open.fda.gov/apis/authentication/. If the variable is missing from
```
.env
```
, do NOT ask the user to paste it into the chat (this would leak the key into the agent's context). Instead, give the user this command — substituting
ENV_FILE
with the resolved literal path to the
.env
file:
bash
```
printf "Enter openFDA API key (typing hidden): " && read -s key && echo && echo "FDA_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
```
The scripts load credentials automatically via
```
dotenv
```
. NEVER read, print, or inspect the
```
.env
```
file or its variables (e.g. no
```
cat
```
,
```
grep
```
,
```
echo
```
,
```
printenv
```
, or
```
os.environ.get
```
on keys). Credentials must stay out of the agent's context.

uv
：阅读
```
uv
```
技能文档并遵循其设置说明，确保
```
uv
```
已安装并添加至PATH。
用户通知：如果技能目录中不存在LICENSE_NOTIFICATION.txt文件，则(1) 显著提醒用户查看https://open.fda.gov/apis/和https://open.fda.gov/license上的条款，然后(2) 创建该文件并记录通知文本和时间戳。
.env
文件：确保主目录中存在
```
.env
```
文件，若不存在则创建一个。
FDA_API_KEY
（可选但推荐）：将每日请求限制从1000次提升至120000次。即使没有该密钥，技能也能运行，但智能体在单次会话中很容易耗尽无密钥限制的请求次数。用户可在https://open.fda.gov/apis/authentication/注册免费密钥。如果`.env`文件中缺少该变量，请勿要求用户在聊天中粘贴密钥（这会导致密钥泄露至智能体上下文）。相反，请向用户提供以下命令——**将`ENV_FILE`替换为`.env`文件的实际路径**：
bash
```
printf "Enter openFDA API key (typing hidden): " && read -s key && echo && echo "FDA_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
```
脚本会通过
```
dotenv
```
自动加载凭据。绝对不要读取、打印或检查
```
.env
```
文件或其变量（例如，不要对密钥使用
```
cat
```
、
```
grep
```
、
```
echo
```
、
```
printenv
```
或
```
os.environ.get
```
）。凭据必须远离智能体上下文。

Core Rules

核心规则

Use the Wrapper: ALWAYS execute the provided helper scripts to query the database rather than accessing the database directly. The scripts automatically enforce the required rate limit gracefully.
Rate Limiting: Respect openFDA rate limits. Without API key: 240 requests/min, 1,000 requests/day per IP. With API key: 240 requests/min, 120,000 requests/day per key. Always set an API key before running multi-query workflows.

Warning: An automated agent can easily exhaust the 1,000-request daily limit in a single research session. Always set an API key before running multi-query workflows.

Instruct the user to register for a free key at https://open.fda.gov/apis/authentication/ and follow the prerequisite instructions above to add
FDA_API_KEY
to the
.env
file. The script will emit a warning to stderr if no API key is detected.

Always Use
--output
: All subcommands require
```
--output <file>
```
to write results to a file. This prevents large output becoming overwhelming. Use jq or code to read the output file.
Notification: If this skill is used, ensure this is mentioned in the output.

使用封装脚本：始终执行提供的辅助脚本来查询数据库，而非直接访问数据库。脚本会自动优雅地执行必要的速率限制。
速率限制：遵守openFDA的速率限制。无API密钥时：每IP每分钟240次请求，每天1000次请求。有API密钥时：每分钟240次请求，每天120000次请求。在运行多查询工作流前，务必设置API密钥。

警告：自动化智能体在单次研究会话中很容易耗尽1000次请求的每日限制。在运行多查询工作流前，务必设置API密钥。

指导用户在https://open.fda.gov/apis/authentication/注册免费密钥，并按照上述前提条件说明将`FDA_API_KEY`添加至`.env`文件。如果未检测到API密钥，脚本会向stderr发出警告。

始终使用
--output
：所有子命令都需要
```
--output <file>
```
参数将结果写入文件。这可避免大量输出造成信息过载。使用jq或代码读取输出文件。
通知：如果使用了本技能，请确保在输出中提及这一点。

Utility Script

实用脚本

Single script for all operations:

bash

uv run scripts/openfda_query.py {search,count,download} --output <file> [options]

所有操作均使用单个脚本：

bash

uv run scripts/openfda_query.py {search,count,download} --output <file> [options]

1. Search

1. 搜索

Search any of the 28 endpoints and save JSON results to a file.

bash

uv run scripts/openfda_query.py search \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --limit 5 --output /tmp/fda_results.json

Stdout prints a compact summary:

json

{"status": "success", "output": "/tmp/fda_results.json", "results_in_file": 5, "total_matching": 601477}

Options:

```
--output
```
: Output file for full JSON results (required).

--category

: API category —

drug

device

food

tobacco

other

animalandveterinary

cosmetic

transparency

```
--endpoint
```
: Endpoint within the category (e.g.,
```
event
```
,
```
label
```
,
```
510k
```
). See references/api_endpoints.md for full list.

--search

: Query string (e.g.,

patient.drug.medicinalproduct:aspirin+AND+serious:1

```
--sort
```
: Sort field and order (e.g.,
```
receivedate:desc
```
).
```
--limit
```
: Max results (default 10, max 1000).
```
--skip
```
: Pagination offset (default 0).
```
--api_key
```
: API key (also reads
```
FDA_API_KEY
```
env var).

搜索任意28个端点并将JSON结果保存至文件。

bash

uv run scripts/openfda_query.py search \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --limit 5 --output /tmp/fda_results.json

标准输出会打印简洁摘要：

json

{"status": "success", "output": "/tmp/fda_results.json", "results_in_file": 5, "total_matching": 601477}

选项：

```
--output
```
：完整JSON结果的输出文件（必填）。

--category

：API类别 —

drug

device

food

tobacco

other

animalandveterinary

cosmetic

transparency

。

```
--endpoint
```
：类别内的端点（例如
```
event
```
,
```
label
```
,
```
510k
```
）。完整列表请参见references/api_endpoints.md。

--search

：查询字符串（例如

patient.drug.medicinalproduct:aspirin+AND+serious:1

）。

```
--sort
```
：排序字段和顺序（例如
```
receivedate:desc
```
）。
```
--limit
```
：最大结果数（默认10，最大1000）。
```
--skip
```
：分页偏移量（默认0）。
```
--api_key
```
：API密钥（也会读取
```
FDA_API_KEY
```
环境变量）。

2. Count

2. 统计

Count unique values of a field within matching results.

bash

uv run scripts/openfda_query.py count \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --count_field "patient.reaction.reactionmeddrapt.exact" \
  --summary 10 --output /tmp/aspirin_reactions.json

Stdout prints a summary with the top 5 terms. Full data is in the output file.

Additional options:

```
--count_field
```
: Field to count (append
```
.exact
```
for whole-phrase counting).
```
--summary N
```
: Return only the top N most frequent terms. Use this to avoid flooding the context with hundreds of infrequent terms.

统计匹配结果中某个字段的唯一值数量。

bash

uv run scripts/openfda_query.py count \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --count_field "patient.reaction.reactionmeddrapt.exact" \
  --summary 10 --output /tmp/aspirin_reactions.json

标准输出会打印包含前5个术语的摘要，完整数据在输出文件中。

额外选项：

```
--count_field
```
：要统计的字段（添加
```
.exact
```
后缀可进行整词匹配统计）。
```
--summary N
```
：仅返回前N个最频繁的术语。使用此选项可避免上下文被数百个低频术语淹没。

3. Download

3. 下载

Download multiple pages of results to a file.

bash

uv run scripts/openfda_query.py download \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --limit 100 --max_pages 5 \
  --output /tmp/aspirin_events.json

Additional options:

```
--max_pages
```
: Maximum pages to fetch (default 10).
```
--all_results
```
: Automatically paginate to fetch all matching results. Safety cap of 25,000 records maximum per download to prevent runaway downloads and prevent excessive API usage.
Tip: Common drugs can have excessive reports. Use a date range (e.g.,
```
receivedate:[20250101+TO+20250131]
```
) to limit the volume of download.

下载多页结果至文件。

bash

uv run scripts/openfda_query.py download \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --limit 100 --max_pages 5 \
  --output /tmp/aspirin_events.json

额外选项：

```
--max_pages
```
：要获取的最大页数（默认10）。
```
--all_results
```
：自动分页以获取所有匹配结果。每次下载最多获取25000条记录的安全上限，以防止失控下载和过度API使用。
提示：常见药物可能有大量报告。使用日期范围（例如
```
receivedate:[20250101+TO+20250131]
```
）来限制下载量。

Entity Resolution: Using .exact for Precision

实体解析：使用.exact提高精度

When searching for specific product names, drug names, or categorical terms, always use the

.exact

suffix on the field to get exact-match results. Without it, the API tokenizes multi-word values and returns noisy partial matches.

bash

undefined

当搜索特定产品名称、药物名称或分类术语时，务必在字段后添加

.exact

后缀以获取精确匹配结果。如果不添加，API会对多词值进行分词，返回嘈杂的部分匹配结果。

bash

undefined

Precise: matches only "ADVIL"

精确匹配：仅匹配"ADVIL"

uv run scripts/openfda_query.py search --category drug --endpoint label
--search 'openfda.brand_name.exact:"ADVIL"'
--limit 5 --output /tmp/advil_label.json


> **Note**: Many brand names in the FDA database include variant suffixes (e.g.,
> "TYLENOL Extra Strength" rather than just "TYLENOL"). If an `.exact` search
> returns 0 results, try without `.exact` to see the available brand name
> variants, then re-query with the full exact name.

The `.exact` suffix is also required when using `--count_field` to aggregate
whole phrases instead of individual words.

uv run scripts/openfda_query.py search --category drug --endpoint label
--search 'openfda.brand_name.exact:"ADVIL"'
--limit 5 --output /tmp/advil_label.json


> **注意**：FDA数据库中的许多品牌名称包含变体后缀（例如“TYLENOL Extra Strength”而非仅“TYLENOL”）。如果`.exact`搜索返回0条结果，尝试不使用`.exact`查看可用的品牌名称变体，然后使用完整的精确名称重新查询。

在使用`--count_field`聚合整词而非单个单词时，也需要`.exact`后缀。

MedDRA Term Resolution

MedDRA术语解析

openFDA adverse event data uses MedDRA (Medical Dictionary for Regulatory Activities) terms for reactions. The API reports Preferred Terms (PTs) but does not provide the MedDRA hierarchy (System Organ Class, High Level Terms, etc.).

Note: MedDRA is a proprietary ontology and is not indexed in the EMBL-EBI OLS. To approximate MedDRA hierarchy lookups, use the Human Phenotype Ontology (HP) or NCI Thesaurus (NCIT) as proxy ontologies — they cross-reference MedDRA IDs and provide parent/ancestor relationships.

bash

undefined

openFDA不良事件数据使用MedDRA（监管活动医学词典）术语来描述不良反应。API会报告首选术语（PTs），但不提供MedDRA层级（系统器官分类、高级术语等）。

注意：MedDRA是专有本体，未在EMBL-EBI OLS中索引。要近似MedDRA层级查询，请使用**人类表型本体（HP）或NCI词库（NCIT）**作为代理本体——它们交叉引用MedDRA ID并提供父/祖先关系。

bash

undefined

Step 1: Get top reactions from openFDA

步骤1：从openFDA获取主要不良反应术语

uv run scripts/openfda_query.py count
--category drug --endpoint event
--search "patient.drug.medicinalproduct:metformin"
--count_field "patient.reaction.reactionmeddrapt.exact"
--summary 5 --output /tmp/metformin_reactions.json

Step 2: Look up the top reaction term using a biomedical ontology service

步骤2：使用生物医学本体服务技能（例如embl-ebi-ols技能）查询排名靠前的不良反应术语。

skill (e.g. embl-ebi-ols skill).

MedDRA在OLS中不可用；使用人类表型本体（HP）或NCI词库（NCIT）作为代理来查找不良反应术语的层级分类。

MedDRA is not available in OLS; use the Human Phenotype Ontology (HP) or

—

NCI Thesaurus (NCIT) as a proxy to find the hierarchical classification of

—

the reaction term.

—

undefined

undefined

Available Endpoints (28 total)

可用端点（共28个）

Category to endpoint mapping:

```
drug
```
: event, label, ndc, enforcement, drugsfda, shortages
```
device
```
: 510k, classification, enforcement, event, pma, recall, registrationlisting, udi, covid19serology
```
food
```
: enforcement, event
```
tobacco
```
: problem, researchpreventionads, researchdigitalads, researchsmokefree
```
other
```
: historicaldocument, nsde, substance, unii
```
animalandveterinary
```
: event
```
cosmetic
```
: event
```
transparency
```
: crl

类别与端点映射：

```
drug
```
：event, label, ndc, enforcement, drugsfda, shortages
```
device
```
：510k, classification, enforcement, event, pma, recall, registrationlisting, udi, covid19serology
```
food
```
：enforcement, event
```
tobacco
```
：problem, researchpreventionads, researchdigitalads, researchsmokefree
```
other
```
：historicaldocument, nsde, substance, unii
```
animalandveterinary
```
：event
```
cosmetic
```
：event
```
transparency
```
：crl

Reference

参考资料

Query syntax and all endpoints: See references/api_endpoints.md for field names, search syntax, date ranges, and boolean operators.

查询语法及所有端点：字段名称、搜索语法、日期范围和布尔运算符请参见references/api_endpoints.md。

Recipes

常用示例

Common query patterns for drugs, devices, foods, tobacco, cosmetics, animal and veterinary products, substances, transparency data, adverse events, recalls, labeling, approvals, shortages, 510(k) clearances, NDC lookups, any FDA safety or regulatory data query, and more. See references/recipes.md for the full recipes.

针对药物、器械、食品、烟草、化妆品、动物及兽药产品、物质、透明度数据、不良事件、召回、标签、批准、短缺、510(k) clearance、NDC查询及任何FDA安全或监管数据查询的常见查询模式。完整示例请参见references/recipes.md。

Workflow

工作流程

Search for records using
```
search
```
with
```
--output
```
. Read the output file.
Use
```
count
```
with
```
--summary 10 --output
```
to summarize field distributions.
Use
```
download
```
(with
```
--all_results
```
for exhaustive pulls) to fetch larger datasets.
Read and analyze the output file using standard tools.
For MedDRA term hierarchy questions, use a biomedical ontology service skill (e.g. EMBL-EBI OLS skill with the HP or NCIT ontology) to look up the term.

使用带
```
--output
```
参数的
```
search
```
命令搜索记录，读取输出文件。
使用带
```
--summary 10 --output
```
参数的
```
count
```
命令汇总字段分布。
使用
```
download
```
命令（如需完整获取结果则添加
```
--all_results
```
参数）获取更大数据集。
使用标准工具读取和分析输出文件。
若涉及MedDRA术语层级问题，使用生物医学本体服务技能（例如使用HP或NCIT本体的EMBL-EBI OLS技能）查询术语。