alterlab-fda

FDA 数据库访问

概述

通过 openFDA 访问全面的 FDA 监管数据。openFDA 是 FDA 提供公共数据集开放 API 的计划。使用 Python 和标准化接口查询药品、医疗器械、食品、动物／兽医产品及物质相关信息。

主要功能：

• 查询药品、器械、食品和兽医产品的不良事件
• 访问产品标签、审批信息和监管申报
• 监测召回和执法行动
• 查询国家药品代码（NDC）和物质标识符（UNII）
• 分析器械分类和许可信息（510k、PMA）
• 跟踪药品短缺和供应问题
• 研究化学结构和物质关系

何时使用此技能

在以下场景中使用此技能：

• 药品研究：安全性概况、不良事件、标签、审批、短缺
• 医疗器械监测：不良事件、召回、510(k) 许可、PMA 审批
• 食品安全：召回、过敏原跟踪、不良事件、膳食补充剂
• 兽医学：按物种和品种查询动物药品不良事件
• 化学／物质数据：查询 UNII、映射 CAS 编号、分子结构
• 监管分析：审批途径、执法行动、合规跟踪
• 药物警戒：上市后监测、安全信号检测
• 科学研究：药物相互作用、比较安全性、流行病学研究

不适用场景

场景	改用
临床试验注册记录（NCT ID、招募情况、资格标准）	alterlab-clinicaltrials
来自 DrugBank 的精选药物—靶点／DDI 知识	alterlab-drugbank
化合物生物活性和作用机制数据	alterlab-chembl
药物基因组学剂量指导（CPIC/DPWG）	alterlab-clinpgx

快速入门

1. 基本设置

# Run from the skill's scripts/ dir, or add it to sys.path first.
from fda_query import FDAQuery

# API key is optional (works keyless); pass it or set FDA_API_KEY.
fda = FDAQuery(api_key="YOUR_API_KEY")

# Query drug adverse events
events = fda.query_drug_events("aspirin", limit=100)

# Get drug labeling
label = fda.query_drug_label("Lipitor", brand=True)

# Search device recalls
recalls = fda.query("device", "enforcement",
                   search="classification:Class+I",
                   limit=50)

2. API 密钥设置

无需密钥也可使用此 API，但注册后可获得更高的速率限制：

• 不使用密钥：每分钟 240 次请求，每天 1,000 次
• 使用密钥：每分钟 240 次请求，每天 120,000 次

在此注册：https://open.fda.gov/apis/authentication/

将其设为环境变量：

export FDA_API_KEY="your_key_here"

3. 运行示例

# Run comprehensive examples
python scripts/fda_examples.py

# This demonstrates:
# - Drug safety profiles
# - Device surveillance
# - Food recall monitoring
# - Substance lookup
# - Comparative drug analysis
# - Veterinary drug analysis

FDA 数据库类别

药品

访问涵盖药品完整生命周期的 6 个相关端点，从审批到上市后监测均有涉及。

端点：

1. 不良事件 - 副作用、错误和治疗失败报告
2. 产品标签 - 处方信息、警告、适应症
3. NDC 目录 - 国家药品代码产品信息
4. 执法报告 - 药品召回和安全行动
5. Drugs@FDA - 自 1939 年以来的历史审批数据
6. 药品短缺 - 当前和已解决的供应问题

常见用例：

# Safety signal detection
fda.count_by_field("drug", "event",
                  search="patient.drug.medicinalproduct:metformin",
                  field="patient.reaction.reactionmeddrapt")

# Get prescribing information
label = fda.query_drug_label("Keytruda", brand=True)

# Check for recalls
recalls = fda.query_drug_recalls(drug_name="metformin")

# Monitor shortages (endpoint is drug/shortages; status values:
# "Current", "To Be Discontinued", "Resolved")
shortages = fda.query("drug", "shortages",
                     search="status:Current")

**参考：**详细文档见 references/drugs.md

器械

访问涵盖医疗器械安全、审批和注册的 9 个相关端点。

端点：

1. 不良事件 - 器械故障、伤害、死亡
2. 510(k) 许可 - 上市前通知
3. 分类 - 器械类别和风险等级
4. 执法报告 - 器械召回
5. 召回 - 详细召回信息
6. PMA - III 类器械上市前审批数据
7. 注册与列名 - 制造设施数据
8. UDI - 唯一器械标识数据库
9. COVID-19 血清学 - 抗体检测性能数据

常见用例：

# Monitor device safety
events = fda.query_device_events("pacemaker", limit=100)

# Look up device classification
classification = fda.query_device_classification("DQY")

# Find 510(k) clearances
clearances = fda.query_device_510k(applicant="Medtronic")

# Search by UDI
device_info = fda.query("device", "udi",
                       search="identifiers.id:00884838003019")

**参考：**详细文档见 references/devices.md

食品

访问 2 个与食品相关的端点，用于安全监测和召回。

端点：

1. 不良事件 - 食品和膳食补充剂相关事件（CAERS；food/event）
2. 执法报告 - 食品召回

化妆品不良事件现有独立端点 cosmetic/event。

常见用例：

# Monitor allergen recalls
recalls = fda.query_food_recalls(reason="undeclared peanut")

# Track dietary supplement events
events = fda.query_food_events(
    industry="Dietary Supplements")

# Find contamination recalls
listeria = fda.query_food_recalls(
    reason="listeria",
    classification="I")

参考： 详细文档请参阅 references/foods.md

动物与兽医

访问兽药不良事件数据，其中包含物种特定信息。

端点：

1. 不良事件 - 按物种、品种和产品分类的动物药物副作用

常见用例：

# Species-specific events
dog_events = fda.query_animal_events(
    species="Dog",
    drug_name="flea collar")

# Breed predisposition analysis
breed_query = fda.query("animalandveterinary", "event",
    search="reaction.veddra_term_name:*seizure*+AND+"
           "animal.breed.breed_component:*Labrador*")

参考： 详细文档请参阅 references/animal_veterinary.md

物质及其他

访问分子级物质数据，其中包含 UNII 代码、化学结构和关联关系。

端点：

1. 物质数据（other/substance）- UNII、CAS、化学结构、关联关系
2. UNII（other/unii）- UNII 代码 ↔ 物质名称查询
3. NSDE（other/nsde）- 完整的 NDC SPL 数据元素文件
4. 历史文档（other/historicaldocument）- FDA 归档文档

此外还有以下在线端点（已于 2026-09 验证）：transparency/crl（已发布的完整回复函） 和 tobacco/problem（烟草产品问题报告）。

常见用例：

# UNII to CAS mapping
substance = fda.query_substance_by_unii("R16CO5Y76E")

# Search by name
results = fda.query_substance_by_name("acetaminophen")

# Get chemical structure
structure = fda.query("other", "substance",
    search="names.name:ibuprofen+AND+substanceClass:chemical")

参考： 详细文档请参阅 references/other.md

查询模式与结果处理

可复用的 FDAQuery 模式（安全概况、时间趋势、比较查询和跨数据库查询）、响应结构、错误处理、分页及最佳实践，详见 references/query_patterns.md。

请牢记以下要点：

• 使用特定字段搜索（patient.drug.medicinalproduct:aspirin），而不是不加限定的通配符。
• FDAQuery 会自动处理速率限制（使用密钥时为 240 次/分钟、120,000 次/天）和缓存。
• skip 上限为 25,000（query_all 会在此处停止）；如需查询更深的数据，可使用 Link 响应头中的 search_after 游标、缩小日期范围进行搜索，或使用批量下载。meta.last_updated 会告知各端点数据的最新时间——FAERS（drug/event）会滞后一个季度。
• 使用 count_by_field 时，设置 exact=True 可统计完全匹配的短语（会添加 .exact）。
• 所有响应都采用 {meta: {results: {total, ...}}, results: [...]} 结构；务必检查是否存在 error，以及 results 是否为空。

API 参考

详细信息请参阅：

• 身份验证和速率限制 → 请参阅 references/api_basics.md
• 查询模式与结果处理 → 请参阅 references/query_patterns.md
• 药品数据库 → 请参阅 references/drugs.md
• 器械数据库 → 请参阅 references/devices.md
• 食品数据库 → 请参阅 references/foods.md
• 动物/兽医数据库 → 请参阅 references/animal_veterinary.md
• 物质数据库 → 请参阅 references/other.md

脚本

scripts/fda_query.py

主要查询模块，提供 FDAQuery 类，包含：

• 统一访问所有 FDA 端点的接口
• 自动处理速率限制和缓存
• 错误处理和重试逻辑
• 常见查询模式

scripts/fda_examples.py

全面的示例，演示如何：

• 分析药品安全概况
• 监测器械
• 跟踪食品召回
• 查询物质
• 比较药品
• 分析兽药

运行示例：

python scripts/fda_examples.py

其他资源

• openFDA 主页：https://open.fda.gov/
• API 文档：https://open.fda.gov/apis/
• 交互式 API 浏览器：https://open.fda.gov/apis/try-the-api/
• GitHub 仓库：https://github.com/FDA/openfda
• 服务条款：https://open.fda.gov/terms/

支持与故障排除

常见问题

问题：超出速率限制

• 解决方案：使用 API 密钥、设置延迟，或降低请求频率

问题：未找到结果

• 解决方案：尝试更宽泛的搜索词、检查拼写，或使用通配符

问题：查询语法无效

• 解决方案：查看 references/api_basics.md 中的查询语法

问题：结果中缺少字段

• 解决方案：并非所有记录都包含所有字段；请务必检查字段是否存在

获取帮助

• GitHub Issues：https://github.com/FDA/openfda/issues
• 电子邮件：[email protected]