clinical-trial-finder

Source: https://github.com/aipoch/medical-research-skills

Domain Decisions

• Source database: ClinicalTrials.gov API v2 (https://clinicaltrials.gov/api/v2) — the authoritative US registry mandated by FDAAA 801 (2007) and mirrored by WHO ICTRP. Chosen over EudraCT/EUCTR because it covers the largest global trial volume (>500 000 studies), provides a stable versioned REST API, and is the primary registry for FDA-regulated interventions. Reference: Zarin et al., NEJM 2011; 364:852–860.

• Query field: query.cond (condition/disease field), not query.term (free-text across all fields). query.cond is indexed against MeSH descriptors by the NLM indexing pipeline, giving substantially better recall for condition queries than unstructured text search. Reference: ClinicalTrials.gov API v2 specification, https://clinicaltrials.gov/data-api/api.

• MeSH condition coding: MeSH IDs are read from derivedSection.conditionBrowseModule.meshes — the NLM-curated MeSH mapping that ClinicalTrials.gov computes internally during study indexing. This avoids a separate NLM API call and uses the same vocabulary that query.cond is indexed against, ensuring query/result consistency. Reference: NLM Medical Subject Headings, https://www.nlm.nih.gov/mesh/.

• Max results: 20 trials per query by default (configurable with --max-results). Clinical actionability does not scale with result volume — a clinician reviewing >20 trials without eligibility pre-screening is unlikely to act on any. The default balances coverage with usability.

• Status display: All statuses returned are shown — no pre-filtering. Recruiting trials are highlighted; TERMINATED and WITHDRAWN trials are flagged with a distinct visual indicator and never omitted. Selective display of only active trials would introduce reporting bias and obscure negative evidence. Reference: Chan et al., PLoS Med 2004; 1:e62 (trial publication bias).

• Phase reporting: Phases are reported verbatim from the API and mapped to HL7 FHIR R4 ResearchStudy.phase codes. No lay-term substitution is made to preserve accuracy and avoid misrepresentation.

• FHIR version: FHIR R4, not R5. The ONC 21st Century Cures Act Final Rule (2020) mandates FHIR R4 for certified EHR systems in the US, making R4 the de facto standard for EHR interoperability with Epic, Cerner, and Oracle Health. R5 is in early adoption as of 2026 — using R5 would reduce compatibility with deployed infrastructure. Reference: 45 CFR Part 170, https://www.healthit.gov/cures/sites/default/files/cures/2020-03/ONCCuresActFinalRule.pdf.

• FHIR resource type: ResearchStudy — the canonical HL7 FHIR R4 resource for clinical trials. Status and phase codes map verbatim from the published R4 value sets: research-study-status (http://hl7.org/fhir/research-study-status) and research-study-phase (http://terminology.hl7.org/CodeSystem/research-study-phase).