alterlab-clinicaltrials

ClinicalTrials.gov データベース

概要

ClinicalTrials.gov は、米国国立医学図書館が管理する、世界各地で実施された臨床試験の包括的な登録簿です。API v2 を利用すると、試験を検索し、試験の詳細情報を取得して、さまざまな条件で絞り込み、分析用にデータをエクスポートできます。API は公開されており、認証は不要です。レート制限は約 1 分あたり 50 リクエストで、JSON 形式と CSV 形式に対応しています。

このスキルを使用する場面

以下のような状況で臨床試験データを扱う場合に、このスキルを使用してください。

• 患者のマッチング - 特定の疾患や患者集団を対象に、参加者を募集している試験を探す
• 研究分析 - 臨床試験の傾向、結果、または試験デザインを分析する
• 医薬品／介入の研究 - 特定の医薬品や介入を検証する試験を特定する
• 地域別検索 - 特定の場所や地域で試験を探す
• スポンサー／組織の追跡 - 特定の機関が実施する試験を探す
• データのエクスポート - 追加分析や報告用に臨床試験データを抽出する
• 試験のモニタリング - 特定の試験のステータス更新や結果を追跡する
• 適格性のスクリーニング - 試験の選択基準／除外基準を確認する

該当しない場合

状況	代わりに使用するもの
公表済みの試験結果、RCT 論文、またはメタ分析の文献	alterlab-pubmed
FDA の承認、医薬品ラベル、有害事象（FAERS）、またはリコールのデータ	alterlab-fda
CSR、SAE ナラティブ、またはその他の試験報告書を作成する	alterlab-clinical-reports
エビデンスレベルに基づく治療推奨／意思決定アルゴリズム	alterlab-clinical-decision

クイックスタート

基本的な検索クエリ

このスキルの scripts/ ディレクトリからヘルパースクリプトを実行します。

python3 scripts/query_clinicaltrials.py

または、requests ライブラリを使って Python を直接使用します。注：API は countTotal=true を指定しない限り totalCount を返しません。また、ページネーショントークンは nextPageToken として 返されます。

import requests

url = "https://clinicaltrials.gov/api/v2/studies"
params = {
    "query.cond": "breast cancer",
    "filter.overallStatus": "RECRUITING",
    "pageSize": 10,
    "countTotal": "true",  # required for data['totalCount'] to exist
}

response = requests.get(url, params=params)
data = response.json()

print(f"Found {data['totalCount']} trials")

特定の試験を取得する

NCT ID を使って、試験の詳細情報を取得します。

import requests

nct_id = "NCT04852770"
url = f"https://clinicaltrials.gov/api/v2/studies/{nct_id}"

response = requests.get(url)
study = response.json()

# Access specific modules
title = study['protocolSection']['identificationModule']['briefTitle']
status = study['protocolSection']['statusModule']['overallStatus']

主な機能

1. 疾患／病態別に検索する

query.cond パラメーターを使用して、特定の病態や疾患を研究する試験を探します。

例：参加者を募集している糖尿病試験を探す

from scripts.query_clinicaltrials import search_studies

results = search_studies(
    condition="type 2 diabetes",
    status="RECRUITING",
    page_size=20,
    sort="LastUpdatePostDate:desc"
)

print(f"Found {results['totalCount']} recruiting diabetes trials")
for study in results['studies']:
    protocol = study['protocolSection']
    nct_id = protocol['identificationModule']['nctId']
    title = protocol['identificationModule']['briefTitle']
    print(f"{nct_id}: {title}")

一般的な使用例：

• 希少疾患を対象とする試験を探す
• 併存疾患を対象とする試験を特定する
• 特定の診断に関する試験の実施状況を追跡する

2. 介入／医薬品別に検索する

query.intr パラメーターを使用して、特定の介入、医薬品、医療機器、または処置を検証する試験を検索します。

例：ペムブロリズマブを検証する第 3 相試験を探す

from scripts.query_clinicaltrials import search_studies

results = search_studies(
    intervention="Pembrolizumab",
    status=["RECRUITING", "ACTIVE_NOT_RECRUITING"],
    page_size=50
)

# Filter by phase in results
phase3_trials = [
    study for study in results['studies']
    if 'PHASE3' in study['protocolSection'].get('designModule', {}).get('phases', [])
]

相による絞り込みに関する注意： filter.phase クエリパラメーターは存在しません。これを渡すと HTTP 400 が返されます。サーバー側で絞り込むには、aggFilters=phase:N を使用します。N は 0～4 です（ファセット内の値はスペースで区切ります。たとえば、第 2 相または第 3 相には aggFilters=phase:2 3 を使用します）。または、Essie 構文で filter.advanced=AREA[Phase](PHASE2 OR PHASE3) を使用します。すでに完全なレコードが必要な場合は、 （上記のように）designModule.phases で後処理フィルタリングするのが最も簡単です。

一般的な使用例：

• 医薬品開発の追跡
• 製薬会社の競合情報の収集
• 臨床医向けの治療選択肢の調査

3. 地域別に検索する

query.locn パラメーターを使用して、特定の場所で実施される試験を探します。

例：ニューヨークのがん試験を探す

from scripts.query_clinicaltrials import search_studies

results = search_studies(
    condition="cancer",
    location="New York",
    status="RECRUITING",
    page_size=100
)

# Extract location details
for study in results['studies']:
    locations_module = study['protocolSection'].get('contactsLocationsModule', {})
    locations = locations_module.get('locations', [])
    for loc in locations:
        if 'New York' in loc.get('city', ''):
            print(f"{loc['facility']}: {loc['city']}, {loc.get('state', '')}")

一般的な使用例：

• 患者を地域の試験に紹介する
• 地域別の試験分布を分析する
• 新規試験の実施施設を選定する

4. スポンサー／組織別に検索する

query.spons パラメーターを使用して、特定の組織が実施する試験を探します。

例：NCI がスポンサーとなっている試験を探す

from scripts.query_clinicaltrials import search_studies

results = search_studies(
    sponsor="National Cancer Institute",
    page_size=100
)

# Extract sponsor information
for study in results['studies']:
    sponsor_module = study['protocolSection']['sponsorCollaboratorsModule']
    lead_sponsor = sponsor_module['leadSponsor']['name']
    collaborators = sponsor_module.get('collaborators', [])
    print(f"Lead: {lead_sponsor}")
    if collaborators:
        print(f"  Collaborators: {', '.join([c['name'] for c in collaborators])}")

一般的な使用例：

• 機関の研究ポートフォリオを追跡する
• 資金提供組織の優先事項を分析する
• 連携の機会を特定する

5. 試験状況でフィルタリングする

filter.overallStatus パラメーターを使用して、募集状況または完了状況で試験をフィルタリングします。

有効な状況の値：

• RECRUITING - 現在、参加者を募集しています
• NOT_YET_RECRUITING - まだ募集を開始していません
• ENROLLING_BY_INVITATION - 招待による登録のみ受け付けています
• ACTIVE_NOT_RECRUITING - 試験は実施中ですが、募集は終了しています
• SUSPENDED - 一時的に中断しています
• TERMINATED - 予定より早く終了しました
• COMPLETED - 試験が終了しました
• WITHDRAWN - 登録開始前に取り下げられました
• 拡大アクセスのレコードでは AVAILABLE、NO_LONGER_AVAILABLE、 TEMPORARILY_NOT_AVAILABLE、APPROVED_FOR_MARKETING を使用します。また、WITHHELD と UNKNOWN も使われます（全リスト：GET /api/v2/studies/enums）

例：最近完了した結果付きの試験を検索する

from scripts.query_clinicaltrials import search_studies

results = search_studies(
    condition="alzheimer disease",
    status="COMPLETED",
    sort="LastUpdatePostDate:desc",
    page_size=50
)

# Filter for trials with results
trials_with_results = [
    study for study in results['studies']
    if study.get('hasResults', False)
]

print(f"Found {len(trials_with_results)} completed trials with results")

6. 試験の詳細情報を取得する

特定の試験について、適格基準、結果、連絡先、実施場所などの包括的な情報を取得します。

例：適格基準を抽出する

from scripts.query_clinicaltrials import get_study_details

study = get_study_details("NCT04852770")
eligibility = study['protocolSection']['eligibilityModule']

print(f"Eligible Ages: {eligibility.get('minimumAge')} - {eligibility.get('maximumAge')}")
print(f"Eligible Sex: {eligibility.get('sex')}")
print(f"\nInclusion Criteria:")
print(eligibility.get('eligibilityCriteria'))

例：連絡先情報を抽出する

from scripts.query_clinicaltrials import get_study_details

study = get_study_details("NCT04852770")
contacts_module = study['protocolSection']['contactsLocationsModule']

# Overall contacts
if 'centralContacts' in contacts_module:
    for contact in contacts_module['centralContacts']:
        print(f"Contact: {contact.get('name')}")
        print(f"Phone: {contact.get('phone')}")
        print(f"Email: {contact.get('email')}")

# Study locations
if 'locations' in contacts_module:
    for location in contacts_module['locations']:
        print(f"\nFacility: {location.get('facility')}")
        print(f"City: {location.get('city')}, {location.get('state')}")
        if location.get('status'):
            print(f"Status: {location['status']}")

7. ページネーションと一括データ取得

ページネーションを使用して、大量の検索結果を効率的に処理します。

例：条件に一致するすべての試験を取得する

from scripts.query_clinicaltrials import search_with_all_results

# Get all trials (automatically handles pagination)
all_trials = search_with_all_results(
    condition="rare disease",
    status="RECRUITING"
)

print(f"Retrieved {len(all_trials)} total trials")

例：制御しながら手動でページネーションする

from scripts.query_clinicaltrials import search_studies

all_studies = []
page_token = None
max_pages = 10  # Limit to avoid excessive requests

for page in range(max_pages):
    results = search_studies(
        condition="cancer",
        page_size=1000,  # Max page size
        page_token=page_token
    )

    all_studies.extend(results['studies'])

    # Check for next page. The API returns the cursor as 'nextPageToken';
    # you pass it back in as the 'pageToken' request parameter.
    page_token = results.get('nextPageToken')
    if not page_token:
        break

print(f"Retrieved {len(all_studies)} studies across {page + 1} pages")

8. CSV にデータをエクスポートする

試験データを CSV 形式でエクスポートし、表計算ソフトウェアやデータ分析ツールで分析します。

例：CSV ファイルにエクスポートする

from scripts.query_clinicaltrials import search_studies

# Request CSV format
results = search_studies(
    condition="heart disease",
    status="RECRUITING",
    format="csv",
    page_size=1000
)

# Save to file
with open("heart_disease_trials.csv", "w") as f:
    f.write(results)

print("Data exported to heart_disease_trials.csv")

注： CSV 形式では、JSON ディクショナリではなく文字列が返されます。

9. 試験情報を抽出して要約する

概要の把握やレポート作成のために、重要な情報を抽出します。

例：試験の概要を作成する

from scripts.query_clinicaltrials import get_study_details, extract_study_summary

# Get details and extract summary
study = get_study_details("NCT04852770")
summary = extract_study_summary(study)

print(f"NCT ID: {summary['nct_id']}")
print(f"Title: {summary['title']}")
print(f"Status: {summary['status']}")
print(f"Phase: {', '.join(summary['phase'])}")
print(f"Enrollment: {summary['enrollment']}")
print(f"Last Update: {summary['last_update']}")
print(f"\nBrief Summary:\n{summary['brief_summary']}")

10. 複合クエリの戦略

複数のフィルターを組み合わせて、対象を絞り込んだ検索を行います。

例：複数の条件による検索

from scripts.query_clinicaltrials import search_studies

# Find Phase 2/3 immunotherapy trials for lung cancer in California
results = search_studies(
    condition="lung cancer",
    intervention="immunotherapy",
    location="California",
    status=["RECRUITING", "NOT_YET_RECRUITING"],
    page_size=100
)

# Further filter by phase
phase2_3_trials = [
    study for study in results['studies']
    if any(phase in ['PHASE2', 'PHASE3']
           for phase in study['protocolSection'].get('designModule', {}).get('phases', []))
]

print(f"Found {len(phase2_3_trials)} Phase 2/3 immunotherapy trials")

リソース

• scripts/query_clinicaltrials.py — 一般的なクエリパターンのヘルパー： search_studies()、get_study_details()、search_with_all_results() （自動ページネーション）、extract_study_summary()。使用例を確認するには、直接実行してください。
• references/api_reference.md — エンドポイントとパラメーターの仕様、レスポンス モジュール、エラー処理、データ標準（ISO 8601、CommonMark）の全容を記載しています。未確認の API 機能の使用やトラブルシューティング時に読み込んでください。

ベストプラクティス

レート制限の管理

API のレート制限は、1 分あたり約 50 リクエストです。一括でデータを取得する場合：

1. リクエスト数を最小限に抑えるため、ページサイズを最大（1000）にします
2. レート制限エラー（ステータス 429）が発生した場合は、指数バックオフを実装します
3. 大規模なデータ収集では、リクエスト間に遅延を設けます

import time
import requests

def search_with_rate_limit(params):
    try:
        response = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 429:
            print("Rate limited. Waiting 60 seconds...")
            time.sleep(60)
            return search_with_rate_limit(params)  # Retry
        raise

データ構造の参照

API レスポンスはネストされた構造になっています。一般的な情報の主なパスは次のとおりです。

• NCT ID: study['protocolSection']['identificationModule']['nctId']
• タイトル: study['protocolSection']['identificationModule']['briefTitle']
• 状況: study['protocolSection']['statusModule']['overallStatus']
• フェーズ: study['protocolSection']['designModule']['phases']
• 適格性: study['protocolSection']['eligibilityModule']
• 実施場所: study['protocolSection']['contactsLocationsModule']['locations']
• 介入: study['protocolSection']['armsInterventionsModule']['interventions']

エラー処理

すべてのリクエストに timeout を設定し、HTTP 400 は「該当する試験がない」ではなく、クエリの不具合として扱ってください。 API は未知のパラメーター（例：filter.phase）や形式が不正な Essie 式を拒否し、400 を返します。

欠損データの処理

すべての試験に完全な情報があるとは限りません。必ずフィールドの有無を確認してください。

# Safe navigation with .get()
phases = study['protocolSection'].get('designModule', {}).get('phases', [])
enrollment = study['protocolSection'].get('designModule', {}).get('enrollmentInfo', {}).get('count', 'N/A')

# Check before accessing
if 'resultsSection' in study:
    # Process results
    pass

Technical Specifications

• Base URL: https://clinicaltrials.gov/api/v2
• Authentication: Not required (public API)
• Rate Limit: ~50 requests/minute per IP
• Response Formats: JSON (default), CSV
• Max Page Size: 1000 studies per request (larger values are coerced down to 1000)
• Date Format: ISO 8601
• Text Format: CommonMark Markdown for rich text fields
• API Version: 2.x (v2.0 released March 2024; GET /api/v2/version reports the current build, 2.0.5 as of 2026-09, plus the data timestamp)
• API Specification: OpenAPI 3.0

For complete technical details, see references/api_reference.md.