clinical-trials-database

臨床試験データベース

前提条件

1. uv：uv スキルを読み、セットアップ手順に従って、uv がインストールされ、PATH に設定されていることを確認してください。
2. ユーザーへの通知：ワークスペースのルートディレクトリに .licenses/clinical_trials_database_LICENSE.txt が存在しない場合は、（1）https://clinicaltrials.gov/ の利用規約を確認するようユーザーに目立つ形で通知し、（2）通知文とタイムスタンプを記録したファイルを作成してください。

概要

REST API v2 を介して、ClinicalTrials.gov から世界中の臨床試験データにアクセスします。scripts/clinical_trials_api.py の CLI スクリプトは、一般的なフィルター（フェーズ、年齢層、ステータス、介入、スポンサーなど）用の専用フラグで API をラップするため、生のクエリを組み立てる必要はほとんどありません。

基本ルール

• ラッパーを使用する：データベースに直接アクセスするのではなく、必ず提供されているヘルパースクリプトを実行してデータベースを照会してください。スクリプトは必要なレート制限を自動的に適切に適用します。
• 常に --fields を使用する — 試験の JSON レコードは非常に大きくなる可能性があるため、必要なデータ項目に絞り込んでください。
• 最初に --count-total を使用する — すべてのレコードを取得する前に、結果の件数を確認してください。
• 大規模な結果セットはページネーションする — --limit と --page-token を使用して反復処理してください。
• 検索フィルターを信頼する：詳細な適格性の確認を明示的に求められない限り、結果を手動で再フィルターしないでください。
• 通知：このスキルを使用した場合は、そのことを出力に記載してください。

コンテキスト効率に関する警告

試験の JSON レコードは非常に大きくなる可能性があります。必要なデータ項目だけに応答を絞り込むため、必ず --fields パラメーターを使用してください。ファイルに書き込んだ後は、ファイル全体ではなく、必要なフィールドだけを読み取ってください。

ヒント

--fields の正確なフィールドパスを特定するには、references/studies_schema.md を使用してください。

応答レイアウトの概要

API の応答には、試験のリスト（通常は studies[] 配列）が含まれます。各試験は protocolSection と、任意の resultsSection に分かれています。

ヒント

特定のデータをリクエストして応答を小さく保つには、--fields パラメーターで以下の省略形エイリアスを使用してください。

トップレベルフィールド

• totalCount — クエリに一致する試験の合計数（整数）
• studies[] — 試験オブジェクトの配列
• nextPageToken — ページネーション用のカーソル文字列

一般的な試験フィールド（および省略形エイリアス）

• 識別情報
  • protocolSection.identificationModule.nctId（NCTId）— 試験固有の ID
  • protocolSection.identificationModule.briefTitle（BriefTitle）— 短いタイトル
• ステータス
  • protocolSection.statusModule.overallStatus（OverallStatus）— 募集状況
• 説明
  • protocolSection.descriptionModule.briefSummary（BriefSummary）— 短い説明
• 群と介入
  • protocolSection.armsInterventionsModule.interventions （ArmsInterventionsModule）
• 適格性
  • protocolSection.eligibilityModule.eligibilityCriteria （EligibilityCriteria）— 選択基準／除外基準
  • protocolSection.eligibilityModule.stdAges（StdAge）— CHILD、ADULT など

完全なフィールドパス（Locations、Outcomes、Results）と一般的な --fields の設定例については、references/studies_schema.md を参照してください。

コマンド

試験を検索する

用途：疾患、薬剤、フェーズ、ステータス、年齢層、またはこれらのフィルターの組み合わせで試験を検索します。

uv run scripts/clinical_trials_api.py search \
  --condition "<disease>" \
  --intervention "<drug_or_treatment>" \
  --status "<status>" \
  --phase "<phase>" \
  --age-group "<age_group>" \
  --study-type "<study_type>" \
  --sponsor "<sponsor_name>" \
  --has-results \
  --sort "<field>:<asc|desc>" \
  --fields "<fields>" \
  --limit <N> \
  --count-total \
  --page-token "<token>" \
  --output /tmp/search_results.json

すべてのフラグは省略可能で、AND 条件で組み合わせられます。

フラグの一覧：

• --condition — 検索する疾患または状態（例："cystic fibrosis"）。
• --intervention — 薬剤、医療機器、または治療名（例："pembrolizumab"）。
• --status — 募集状況のフィルター。値：RECRUITING、COMPLETED、 NOT_YET_RECRUITING、ACTIVE_NOT_RECRUITING、ENROLLING_BY_INVITATION、 TERMINATED、SUSPENDED、WITHDRAWN。
• --phase — 試験フェーズのフィルター。値：PHASE1、PHASE2、PHASE3、PHASE4、 EARLY_PHASE1、NA。
• --age-group — 患者の年齢層のフィルター。値：CHILD（0～17）、ADULT （18～64）、OLDER_ADULT（65+）。
• --study-type — 試験の種類。値：INTERVENTIONAL、OBSERVATIONAL、 EXPANDED_ACCESS。
• --sponsor — 主なスポンサーまたは機関名（例："National Cancer Institute"）。
• --has-results — ブール値フラグ（値は不要）。指定すると、ClinicalTrials.gov で結果が公開されている試験に絞り込みます。
• --sort — FieldName:asc または FieldName:desc 形式の並べ替え順。一般的なフィールド： LastUpdatePostDate、EnrollmentCount、StudyFirstPostDate、StartDate。
• --fields — 応答に含める JSON フィールド名をカンマ区切りで指定します。応答を小さくする場合に使用します（例： "NCTId,BriefTitle,OverallStatus,Phase"）。使用可能なフィールドパスについては、 references/studies_schema.md を参照してください。
• --limit — リクエストごとに返す試験の最大数（1～1000、デフォルトは 10）。
• --count-total — ブール値フラグ（値は不要）。指定すると、全ページにわたる一致試験の総数を示す totalCount フィールドが応答に含まれます。
• --page-token — 結果の次のページを取得するために使用する不透明なカーソル文字列です。この値は、前回の検索応答にある nextPageToken フィールドから取得してください。この文字列を自分で作成せず、API 応答からそのままコピーしてください。以下のページネーションのセクションを参照してください。
• --advanced — 専用フラグでは指定できない構造化クエリ用の Essie フィルター式（例："AREA[LocationCountry]United States"）。他のフラグとは AND 条件で組み合わせられます。構文については references/clinical_trials_api.md を参照してください。
• --output — （必須） JSON 応答を書き込むファイルパス。

例 — 積極的に募集している、嚢胞性線維症を対象とした小児の第 3 相試験：

uv run scripts/clinical_trials_api.py search \
  --condition "cystic fibrosis" \
  --status RECRUITING \
  --phase PHASE3 \
  --age-group CHILD \
  --fields "NCTId,BriefTitle,OverallStatus,Phase" \
  --limit 10 \
  --output /tmp/cf_trials.json

例 — 食道がんを対象とした、アテゾリズマブの募集試験：

uv run scripts/clinical_trials_api.py search \
  --condition "esophageal cancer" \
  --intervention "Atezolizumab" \
  --status RECRUITING \
  --fields "NCTId,BriefTitle,Phase" \
  --limit 10 \
  --output /tmp/atezolizumab_trials.json

NCT ID で試験を取得する

用途：NCT 識別子がすでにわかっている特定の試験の詳細をすべて取得します。

uv run scripts/clinical_trials_api.py get-study \
  <nct_id> [--fields "<fields>"] \
  --output /tmp/study.json

--fields を省略すると、使いやすいデフォルトのフィールドセットを返します： NCTId,BriefTitle,OverallStatus,Phase,BriefSummary, ConditionsModule,ArmsInterventionsModule,EligibilityModule

デフォルト応答の構造：

{
  "protocolSection": {
    "identificationModule": {
      "nctId": "NCT00000000",
      "briefTitle": "Study Title"
    },
    "statusModule": {
      "overallStatus": "RECRUITING"
    },
    "descriptionModule": {
      "briefSummary": "This study is about..."
    },
    "conditionsModule": {
      "conditions": [ "Condition Name" ]
    },
    "armsInterventionsModule": {
      "interventions": [ { "type": "DRUG", "name": "Drug Name" } ]
    },
    "eligibilityModule": {
      "eligibilityCriteria": "Inclusion:\n- ...",
      "stdAges": [ "ADULT" ]
    }
  }
}

適格性／選択基準を取得する

用途：患者のマッチングに使用するため、選択／除外基準、年齢範囲、性別要件を取得します。

uv run scripts/clinical_trials_api.py \
  get-eligibility <nct_id> \
  --output /tmp/eligibility.json

タイトルと、適格性モジュール全体（選択／除外基準、年齢範囲、性別）を返すショートカットです。

例 — NCT04886804 の選択基準：

uv run scripts/clinical_trials_api.py \
  get-eligibility NCT04886804 \
  --output /tmp/eligibility_NCT04886804.json

条件に一致する試験の件数を数える

用途：試験の全体像を把握するため、全記録を取得する前に、特定の状態、フェーズ、またはステータスの試験がいくつあるかを確認します。

uv run scripts/clinical_trials_api.py count \
  --condition "<disease>" \
  [--status "<status>"] [--phase "<phase>"] ... \
  --output /tmp/count.json

試験記録を取得せず、検索条件に一致する臨床試験の総数のみを返します。search と同じフィルターフラグを使用できます。

場所／地域で検索する

用途：特定の国、州、または都市に試験を絞り込みます。

AREA[LocationCountry] または AREA[LocationCity] を --advanced とともに使用して、地域で結果を絞り込みます：

uv run scripts/clinical_trials_api.py search \
  --condition "cystic fibrosis" \
  --status RECRUITING \
  --advanced "AREA[LocationCity]New York" \
  --fields "NCTId,BriefTitle" \
  --limit 20 \
  --output /tmp/nyc_cf_trials.json

スポンサー／組織で検索する

用途：スポンサーまたは機関の試験ポートフォリオを確認します。

--sponsor を使用して、特定の機関または企業が実施する試験を検索します：

uv run scripts/clinical_trials_api.py search \
  --sponsor "National Cancer Institute" \
  --fields "NCTId,BriefTitle,LeadSponsorName" \
  --limit 20 \
  --output /tmp/nci_trials.json

複合的な複数条件での検索

用途：複数のフィルター（疾患と薬剤、フェーズと地域、スポンサーなど）を組み合わせた複雑なクエリ。

すべてのフラグは AND で結合されるため、疾患、介入、ステータス、フェーズ、地域、スポンサーを1つのクエリで組み合わせられます。

uv run scripts/clinical_trials_api.py search \
  --condition "pancreatic cancer" \
  --intervention "immunotherapy" \
  --status RECRUITING \
  --phase PHASE3 \
  --advanced "AREA[LocationCountry]United States" \
  --fields "NCTId,BriefTitle,Phase,LeadSponsorName" \
  --limit 20 \
  --output /tmp/panc_trials.json

Raw API クエリ（回避策）

用途：専用フラグでは対応していない、一般的ではないエンドポイントやパラメーターの組み合わせ。

uv run scripts/clinical_trials_api.py raw-query \
  --endpoint <path> \
  --params '<json_dict>' \
  --output /tmp/raw_result.json

ページネーション

結果が --limit を超えると、レスポンスに nextPageToken が含まれます。--page-token に渡すと、次のページを取得できます。

uv run scripts/clinical_trials_api.py search \
  --condition "breast cancer" \
  --status RECRUITING \
  --limit 50 --count-total \
  --output /tmp/breast_cancer_p1.json

uv run scripts/clinical_trials_api.py search \
  --condition "breast cancer" \
  --status RECRUITING \
  --limit 50 --page-token "CAo=" \
  --output /tmp/breast_cancer_p2.json

高度なクエリ

専用フラグでは対応できない複雑なフィルタリングには、Essie 式を指定して --advanced を使用します。

Essie 式とは？ Essie は ClinicalTrials.gov を支える検索エンジンです。Essie 式は一般的なキーワード検索ではなく、特定のフィールド（国やフェーズなど）を対象とする構造化クエリです。

• AREA[Field]Value：特定のフィールドを対象にします。
  • AREA[LocationCountry]United States
  • AREA[Phase]PHASE3
• ブール演算子：AND、OR、NOT で組み合わせます。
• RANGE[min, max]：数値または日付のフィールドに使用します（例：RANGE[500, MAX]）。

構文と使用可能なフィールドについては、references/clinical_trials_api.md を参照してください。

ほかのフラグとは AND で結合されます。

uv run scripts/clinical_trials_api.py search \
  --condition "diabetes" \
  --advanced "AREA[LocationCountry]United States \
    AND AREA[EnrollmentCount]RANGE[500, MAX]" \
  --fields "NCTId,BriefTitle,EnrollmentCount" \
  --output /tmp/diabetes_us_large.json

参考資料

• API パラメーター、列挙値、Essie 構文： references/clinical_trials_api.md
• JSON フィールドパスと --fields の使用例： references/studies_schema.md