clinical-trials-database

Par mkurman · zorai

Interrogez ClinicalTrials.gov via APIv2. À utiliser pour rechercher des essais par pathologie, médicament, lieu, statut ou phase ; récupérer les détails d'un essai par identifiant NCT ; vérifier les critères d'éligibilité/d'inclusion ; comptabiliser les essais par pathologie ou période ; identifier le portefeuille d'essais d'un sponsor ; trouver des essais en cours de recrutement pour la mise en correspondance avec des patients.

npx skills add https://github.com/mkurman/zorai --skill clinical-trials-database

Base de données des essais cliniques

Prérequis

  1. uv : Consultez le skill uv et suivez ses instructions de configuration pour vous assurer que uv est installé et accessible dans votre PATH.
  2. Notification utilisateur : Si le fichier LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de ce skill, alors (1) notifiez l'utilisateur de manière visible pour qu'il consulte les conditions sur https://clinicaltrials.gov/, puis (2) créez le fichier en enregistrant le texte de notification et l'horodatage.

Vue d'ensemble

Accédez aux données mondiales sur les essais cliniques de ClinicalTrials.gov via l'API REST v2. Le script CLI à scripts/clinical_trials_api.py encapsule l'API avec des drapeaux dédiés pour les filtres courants (phase, groupe d'âge, statut, intervention, sponsor, etc.), de sorte que vous n'ayez rarement besoin de construire des requêtes brutes.

Règles essentielles

  • Utilisez le wrapper : TOUJOURS exécuter les scripts d'assistance fournis pour interroger la base de données plutôt que d'y accéder directement. Les scripts appliquent automatiquement la limite de débit requise avec élégance.
  • Toujours utiliser --fields — les enregistrements JSON d'essai peuvent être très volumineux ; limitez-vous aux points de données dont vous avez besoin.
  • Utilisez --count-total en premier — vérifiez le volume de résultats avant de récupérer tous les enregistrements.
  • Paginez les grands ensembles de résultats — utilisez --limit avec --page-token pour itérer.
  • Faites confiance aux filtres de recherche : ne re-filtrez pas manuellement les résultats sauf si on vous demande explicitement de vérifier les critères d'admissibilité détaillés.
  • Notification : Si ce skill est utilisé, assurez-vous que cela est mentionné dans la sortie.

Avertissement sur l'efficacité du contexte

Les enregistrements JSON d'essai peuvent être très volumineux. Toujours utiliser le paramètre --fields pour limiter la réponse aux seuls points de données dont vous avez besoin. Après l'écriture dans un fichier, lisez uniquement les champs dont vous avez besoin plutôt que le fichier entier.

[!TIP] Utilisez references/studies_schema.md pour identifier les chemins exacts des champs pour --fields.

Résumé de la disposition de la réponse

Les réponses API contiennent une liste d'études (généralement dans un tableau studies[]). Chaque étude est divisée en protocolSection et resultsSection optionnel.

[!Tip] Utilisez les alias abrégés ci-dessous avec le paramètre --fields pour demander des données spécifiques et garder les réponses réduites.

Champs de haut niveau

  • totalCount — Total des études correspondant à la requête (entier)
  • studies[] — Tableau d'objets d'étude
  • nextPageToken — chaîne de curseur pour la pagination

Champs d'étude courants (et alias abrégé)

  • Identification
    • protocolSection.identificationModule.nctId (NCTId) — Identifiant d'essai unique
    • protocolSection.identificationModule.briefTitle (BriefTitle) — Titre court
  • Statut
    • protocolSection.statusModule.overallStatus (OverallStatus) — Statut du recrutement
  • Description
    • protocolSection.descriptionModule.briefSummary (BriefSummary) — Courte description
  • Bras et interventions
    • protocolSection.armsInterventionsModule.interventions (ArmsInterventionsModule)
  • Admissibilité
    • protocolSection.eligibilityModule.eligibilityCriteria (EligibilityCriteria) — Inclusion/Exclusion
    • protocolSection.eligibilityModule.stdAges (StdAge) — CHILD, ADULT, etc.

Consultez references/studies_schema.md pour les chemins complets (Emplacements, Résultats, Outcomes) et les recettes --fields courantes.

Commandes

Rechercher des études

Utiliser pour : trouver des essais par maladie, médicament, phase, statut, groupe d'âge, ou toute combinaison de ces filtres.

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

Tous les drapeaux sont optionnels et se combinent via la logique AND.

Référence des drapeaux :

  • --condition — Maladie ou condition à rechercher (par ex. "cystic fibrosis").
  • --intervention — Nom du médicament, appareil ou traitement (par ex. "pembrolizumab").
  • --status — Filtre de statut de recrutement. Valeurs : RECRUITING, COMPLETED, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, ENROLLING_BY_INVITATION, TERMINATED, SUSPENDED, WITHDRAWN.
  • --phase — Filtre de phase d'essai. Valeurs : PHASE1, PHASE2, PHASE3, PHASE4, EARLY_PHASE1, NA.
  • --age-group — Filtre de groupe d'âge du patient. Valeurs : CHILD (0–17), ADULT (18–64), OLDER_ADULT (65+).
  • --study-type — Type d'étude. Valeurs : INTERVENTIONAL, OBSERVATIONAL, EXPANDED_ACCESS.
  • --sponsor — Nom du sponsor principal ou institution (par ex. "National Cancer Institute").
  • --has-results — Drapeau booléen (aucune valeur nécessaire). Quand présent, filtre pour les études qui ont des résultats disponibles sur ClinicalTrials.gov.
  • --sort — Ordre de tri comme FieldName:asc ou FieldName:desc. Champs courants : LastUpdatePostDate, EnrollmentCount, StudyFirstPostDate, StartDate.
  • --fields — Liste séparée par des virgules des noms de champs JSON à inclure dans la réponse. Utilisez ceci pour garder les réponses réduites (par ex. "NCTId,BriefTitle,OverallStatus,Phase"). Consultez references/studies_schema.md pour les chemins de champs disponibles.
  • --limit — Nombre maximal d'études à retourner par requête (1–1000, par défaut 10).
  • --count-total — Drapeau booléen (aucune valeur nécessaire). Quand présent, la réponse inclut un champ totalCount montrant le nombre total d'études correspondantes sur toutes les pages.
  • --page-token — Une chaîne de curseur opaque utilisée pour récupérer la page suivante de résultats. Obtenez cette valeur du champ nextPageToken dans une réponse de recherche précédente. Ne construisez pas cette chaîne vous-même ; copiez-la toujours textuellement depuis la réponse API. Voir la section Pagination ci-dessous.
  • --advanced — Expression de filtre Essie brute pour les requêtes structurées au-delà des drapeaux dédiés (par ex. "AREA[LocationCountry]United States"). Combiné avec d'autres drapeaux via AND. Voir references/clinical_trials_api.md pour la syntaxe.
  • --output — (Requis) Chemin d'accès au fichier où la réponse JSON est écrite.

Exemple — essais pédiatriques de phase 3 pour la fibrose kystique en recrutement actif :

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

Exemple — essais Atezolizumab en recrutement pour le cancer de l'œsophage :

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

Récupérer une étude par identifiant NCT

Utiliser pour : récupérer les détails complets d'un essai spécifique quand vous avez déjà l'identifiant NCT.

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

Retourne un ensemble de champs par défaut utile si --fields est omis : NCTId,BriefTitle,OverallStatus,Phase,BriefSummary, ConditionsModule,ArmsInterventionsModule,EligibilityModule

Structure de la réponse par défaut :

{
  "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" ]
    }
  }
}

Obtenir les critères d'admissibilité / d'inclusion

Utiliser pour : extraire les règles d'inclusion/exclusion, les plages d'âge et les exigences de sexe pour les tâches d'appariement de patients.

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

Raccourci qui retourne le titre et le module d'admissibilité complet (critères d'inclusion/exclusion, plage d'âge, sexe).

Exemple — critères d'inclusion pour NCT04886804 :

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

Compter les études correspondantes

Utiliser pour : explorer le paysage des essais — vérifier combien d'essais existent pour une condition, phase ou statut avant de récupérer les enregistrements complets.

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

Retourne uniquement le nombre total d'essais cliniques correspondant aux critères de recherche sans récupérer les enregistrements d'étude. Accepte les mêmes drapeaux de filtre que search.

Rechercher par lieu / géographie

Utiliser pour : restreindre les essais à un pays, un État ou une ville spécifique.

Utilisez --advanced avec AREA[LocationCountry] ou AREA[LocationCity] pour restreindre les résultats par géographie :

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

Rechercher par sponsor / organisation

Utiliser pour : identifier le portfolio d'essais d'un sponsor ou d'une institution.

Utilisez --sponsor pour trouver les essais menés par une institution ou une entreprise spécifique :

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

Recherche multi-critères combinée

Utiliser pour : des requêtes complexes qui superposent plusieurs filtres (condition et médicament et phase et géographie et sponsor, etc.).

Tous les drapeaux se combinent via AND, vous pouvez donc superposer les conditions, interventions, statut, phase, géographie et sponsor dans une seule requête :

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

Requête API brute (échappatoire)

Utiliser pour : les points de terminaison peu courants ou les combinaisons de paramètres non couverts par les drapeaux dédiés.

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

Pagination

Quand les résultats dépassent --limit, la réponse inclut un nextPageToken. Passez-le avec --page-token pour récupérer la page suivante :

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

Requêtes avancées

Pour un filtrage complexe au-delà des drapeaux dédiés, utilisez --advanced avec une expression Essie.

Qu'est-ce qu'une expression Essie ? Essie est le moteur de recherche alimentant ClinicalTrials.gov. Une expression Essie est une requête structurée qui cible des champs spécifiques (par ex., pays, phase) plutôt que de faire des recherches par mots-clés généraux.

  • AREA[Field]Value : Cible un champ spécifique.
    • AREA[LocationCountry]United States
    • AREA[Phase]PHASE3
  • Opérateurs booléens : Combinez avec AND, OR, NOT.
  • RANGE[min, max] : Pour les champs numériques/de date (par ex. RANGE[500, MAX]).

Voir references/clinical_trials_api.md pour la syntaxe et les champs disponibles.

Elle est combinée avec d'autres drapeaux via 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

Références

  • Paramètres API, valeurs enum et syntaxe Essie : references/clinical_trials_api.md
  • Chemins de champs JSON et recettes --fields : references/studies_schema.md

Skills similaires

omni-query
exploreomni / omni-agent-skills

Interroger la couche sémantique Omni via CLI pour extraire des données structurées.

17
eval-bootstrap
datadog-labs / agent-skills

Générer du code d'évaluation Python à partir de traces de production LLM Datadog.

126
pinecone-full-text-search
pinecone-io / skills

Créer et interroger un index full-text-search Pinecone avec l'API preview.

14
imaging-data-commons
mkurman / zorai

Interroger et télécharger des données d'imagerie médicale publiques depuis NCI IDC.

309
claude-api
anthropics / skills

Construire des applications LLM avec Claude via le SDK officiel adapté au langage.

146 952