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 日あたりのリクエスト上限が 1,000 件から 120,000 件に引き上げられます。このスキルはキーなしでも動作しますが、エージェントは 1 回のセッションでキーなしの上限を簡単に使い切る可能性があります。無料のキーは https://open.fda.gov/apis/authentication/ で登録できます。このスキルがユーザーのリクエストに関連する場合、credentials スキルの安全な認証情報プロトコルを必ず使用して、このキーがあるか確認し、必要に応じて取得を依頼してください。

基本ルール

• ラッパーを使用する：データベースに直接アクセスするのではなく、クエリには必ず付属のヘルパースクリプトを実行してください。スクリプトが必要なレート制限を自動的かつ適切に適用します。

• レート制限：openFDA のレート制限を遵守してください。API キーなしの場合は、IP アドレスごとに 1 分あたり 240 件、1 日あたり 1,000 件です。API キーありの場合は、キーごとに 1 分あたり 240 件、1 日あたり 120,000 件です。複数クエリを実行するワークフローでは、必ず API キーを設定してください。

警告：自動化されたエージェントは、1 回の調査セッションで 1 日あたり 1,000 件の上限を簡単に使い切る可能性があります。複数クエリを実行するワークフローでは、必ず API キーを設定してください。

このスキルがユーザーのリクエストに関連する場合、credentials スキルの安全な認証情報プロトコルを必ず使用して、ユーザーが .env ファイルに FDA_API_KEY を追加できるよう支援してください。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 の過剰な使用を防ぐため、1 回のダウンロードで 最大 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」だけでなく、「TYLENOL Extra Strength」）。.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（Medical Dictionary for Regulatory Activities）の用語が使われています。API は 基本語（PT） を報告しますが、MedDRA の階層（器官別大分類、上位語など）は提供しません。

注：MedDRA は独自仕様のオントロジーであり、EMBL-EBI OLS には索引付けされていません。MedDRA の階層を近似的に検索するには、代理オントロジーとして Human Phenotype Ontology（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 スキル）を使って用語を調べます。