clinicaltrials-database

用途

ClinicalTrials.gov 是由美国国家医学图书馆维护的全球临床试验注册库。本技能用于通过 ClinicalTrials.gov API v2 检索试验、获取详细研究信息、按多种条件过滤并导出数据以供分析。

适用场景包括：患者匹配（为特定疾病或人群寻找正在招募的试验）、研究分析（分析临床试验趋势、结果或研究设计）、药物/干预措施研究、地理检索、申办方/机构追踪、数据导出、试验监测、入组资格筛查。

主要能力

按疾病/状况检索：使用 query.cond 参数查找研究特定医学状况或疾病的试验。
按干预措施/药物检索：使用 query.intr 参数查找测试特定干预措施、药物、器械或操作的试验。
地理检索：使用 query.locn 参数查找特定地点的试验。
按申办方/机构检索：使用 query.spons 参数查找特定组织开展的试验。
按研究状态过滤：使用 filter.overallStatus 参数，有效值包括 RECRUITING、NOT_YET_RECRUITING、ENROLLING_BY_INVITATION、ACTIVE_NOT_RECRUITING、SUSPENDED、TERMINATED、COMPLETED、WITHDRAWN。
获取详细研究信息：包括入组资格标准、结果、联系人与地点等。
分页与批量数据获取：支持自动分页或手动分页控制。
数据导出为 CSV：便于在电子表格或数据分析工具中处理。
提取并汇总研究信息：快速生成试验概览。
组合查询策略：组合多个过滤条件进行定向检索。

使用方式

基础检索可通过辅助脚本执行：

cd scientific-databases/clinicaltrials-database/scripts python3 query_clinicaltrials.py

也可直接使用 Python 的 requests 库调用 API：

import requests

url = "https://clinicaltrials.gov/api/v2/studies" params = { "query.cond": "breast cancer", "filter.overallStatus": "RECRUITING", "pageSize": 10 }

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()

title = study['protocolSection']['identificationModule']['briefTitle'] status = study['protocolSection']['statusModule']['overallStatus']

脚本提供以下辅助函数：search_studies()（带多种过滤条件检索试验）、get_study_details()（获取特定试验完整信息）、search_with_all_results()（自动分页获取全部结果）、extract_study_summary()（提取关键信息用于快速概览）。

技术规格

基础 URL：https://clinicaltrials.gov/api/v2
认证：无需认证（公开 API）
速率限制：约每分钟 50 次请求（按 IP）
响应格式：JSON（默认）、CSV
最大分页大小：每次请求 1000 项研究
日期格式：ISO 8601
文本格式：富文本字段使用 CommonMark Markdown
API 版本：2.0（2024 年 3 月发布）
API 规范：OpenAPI 3.0

限制与注意事项

速率限制管理：批量获取数据时建议使用最大分页大小（1000）以减少请求次数，对速率限制错误（429 状态）实施指数退避，大规模数据收集时在请求之间添加延迟。

数据结构导航：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']）。

错误处理：应对网络请求实施错误处理，包括 HTTP 错误、请求失败与 JSON 解码错误。

缺失数据处理：并非所有试验都有完整信息，访问字段前应检查其是否存在，可使用 .get() 进行安全导航。

CSV 格式说明：请求 CSV 格式时返回的是字符串而非 JSON 字典。

参考文档：references/api_reference.md 提供完整端点规范、所有查询参数与有效值、响应数据结构与模块、常见用例代码示例、错误处理与最佳实践、数据标准等详细 API 文档。

技能介绍

用途

主要能力

使用方式

技术规格

限制与注意事项