openfda-database

openFDA 搜索与查询

前提条件

1. uv：阅读 uv 技能，并按照其中的设置说明操作，确保 已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/openfda_database_LICENSE.txt， 则 (1) 显著提醒用户查看 https://open.fda.gov/apis/ 和 https://open.fda.gov/license 上的条款，然后 (2) 创建该文件，记录 通知文本和时间戳。
3. .env 文件：确保 .env 文件存在于你的主目录中。 如果不存在，则创建一个。
4. FDA_API_KEY（可选，但建议设置）：将每日请求限额从 1,000 次提升至 120,000 次。此技能无需 API 密钥也能使用，但 Agent 可能会在 单个会话中轻易耗尽无密钥限额。如果此技能与用户请求相关，你必须 使用 credentials 技能中的安全凭据协议，检查并申请此密钥。你可以在 https://open.fda.gov/apis/authentication/ 免费注册获取密钥。

核心规则

• 使用包装脚本：查询数据库时，务必执行提供的辅助脚本，而不要直接访问 数据库。这些脚本会自动妥善执行所需的速率限制。

• 速率限制：遵守 openFDA 的速率限制。无 API 密钥时：每个 IP 每分钟 240 次请求、每天 1,000 次请求。使用 API 密钥时：每分钟 240 次请求、 每个密钥每天 120,000 次请求。运行多次查询的工作流前，务必设置 API 密钥。

警告：自动化 Agent 可能会在单次研究会话中轻易耗尽每天 1,000 次的 请求限额。运行多次查询的工作流前，务必设置 API 密钥。

如果此技能与用户请求相关，你必须使用 credentials 技能中的安全凭据协议， 帮助用户将 FDA_API_KEY 添加到其 .env 文件中。如果未检测到 API 密钥，脚本会向 stderr 输出警告。

• 始终使用 --output：所有子命令都必须使用 --output <file> 将结果 写入文件，以免大量输出难以处理。使用 jq 或代码读取输出文件。

• 通知：如果使用了此技能，确保在输出中提及。

实用脚本

所有操作只需使用一个脚本：

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

1. 搜索

搜索 28 个端点中的任意一个，并将 JSON 结果保存到文件。

uv run scripts/openfda_query.py search \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --limit 5 --output /tmp/fda_results.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. 计数

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

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. 下载

将多页结果下载到文件。

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：自动翻页，获取所有匹配结果。 为防止下载失控和过度使用 API，每次下载最多设有 25,000 条记录的安全上限。

  提示：常见药物可能有大量报告。使用日期范围（例如， receivedate:[20250101+TO+20250131]）限制下载量。

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

搜索特定产品名称、药物名称或类别术语时，始终在字段后使用 .exact 后缀，以获取精确匹配结果。不使用该后缀时，API 会将多个词组成的值拆分为词元，从而返回大量不相关的部分匹配结果。

# Precise: matches only "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

注意：FDA 数据库中的许多品牌名称带有变体后缀（例如， "TYLENOL Extra Strength"，而不只是 "TYLENOL"）。如果 .exact 搜索 返回 0 条结果，请尝试不使用 .exact，查看可用的品牌名称变体，然后使用完整的精确名称重新查询。

使用 --count_field 汇总完整词组而非单个词语时，也必须使用 .exact 后缀。

NDC 查询：连字符和已停产药物

1. 务必为带连字符的 NDC 加引号：在 openFDA 搜索语法中，未加引号的 连字符（-）会充当布尔 NOT 运算符（例如，51285-092 会搜索 51285 AND NOT 092）。务必将带连字符的 NDC 字符串放在转义的双引号中：

   uv run scripts/openfda_query.py search --category drug --endpoint ndc \
     --search 'product_ndc:"51285-092"' \
     --limit 5 --output /tmp/ndc.json
   

2. 已停产药物的后备方案（drug/label）：drug/ndc 端点仅包含当前有效/在售产品。如果有效的 NDC 在 drug/ndc 中返回 0 条结果，请使用精确词组引号（--search '"51285-092"'）查询 drug/label 端点。请注意，对于已停产药物，openfda 元数据块可能为空（{}），因此应从标签文本字段（package_label_principal_display_panel、description 或 spl_product_data_elements）中读取品牌名称、活性成分和标签商信息。

MedDRA 术语解析

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

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

# Step 1: Get top reactions from 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
# skill (e.g. embl-ebi-ols skill).
# 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.

可用端点（共 28 个）

类别与端点的映射：

• 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

参考

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

示例方案

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

工作流

1. 使用 search 和 --output 搜索记录。读取输出文件。
2. 使用 count 和 --summary 10 --output 汇总字段分布。
3. 使用 download（穷尽式提取时加上 --all_results）获取较大的数据集。
4. 使用标准工具读取并分析输出文件。
5. 对于 MedDRA 术语层级相关问题，使用生物医学本体服务技能（例如使用 HP 或 NCIT 本体的 EMBL-EBI OLS 技能）查询术语。