🚀 Migration API ClinicalTrials.gov v2 : pagination & endpoints

Comment reconnaître le problème ?

Un script qui fonctionnait avant l'été 2024 peut casser de plusieurs façons : erreur 404, réponse vide interprétée comme « aucune étude », ou arrêt du traitement parce que le parseur n'obtient plus le format attendu.

Le réflexe utile : journaliser le code HTTP et le corps de réponse, au lieu de traiter chaque échec comme si c'était simplement un « résultat de recherche ».

Les vérifications réalisées le 14 octobre 2026 confirment le même comportement pour les anciennes routes (requête et information). Mais le point opérationnel est simple : évitez de construire une nouvelle intégration sur les URL classiques.

Ce qui change réellement pour une intégration

En pratique, le passage à v2 touche trois choses :

• La requête : expr devient query.term, et la logique de pagination change (pagination à curseur).
• La réponse : les champs sont imbriqués dans des modules, et les listes ne sont plus représentées de la même façon.
• L'interprétation : l'ordre n'est pas forcément celui que vous aviez, et les valeurs d'énumération sont généralement des codes en majuscules.

Bref : un ajustement d'URL ne suffit pas. Pour que l'intégration soit fiable, il faut vérifier à la fois le statut HTTP, la forme de la réponse et le sens métier des valeurs récupérées.

Une étude ou un export complet

Pour récupérer une étude précise, utilisez /api/v2/studies/{nctId}. La réponse suit le même schéma que les études dans l'export JSON global. Pour récupérer l'ensemble du registre, /api/v2/studies/download?format=json.zip évite de parcourir tout le monde via pagination.

Le téléchargement complet convient bien pour une copie locale ou un traitement batch, moins pour une application interactive. Au 14 octobre 2026, le registre comptait 606 964 études : attendez-vous à un export volumineux, avec de la place disque et une stratégie de reprise si votre réseau ou votre environnement limite les exécutions.

Remplacer une recherche par champs

Une ancienne requête qui ne demandait que NCTId et BriefTitle peut devenir fields=NCTId,BriefTitle. En v2, toutefois, ces valeurs vivent dans une réponse imbriquée : par exemple, l'identifiant NCT se trouve sous protocolSection.identificationModule.nctId.

C'est important pour les traitements aval : si un export alimente une base relationnelle, un tableau de bord ou un pipeline, vérifiez les colonnes réellement produites après migration. Une requête « valide » ne garantit pas que le schéma attendu par votre application est identique.

Gérer les pages sans perdre de résultats

Par défaut, la taille de page est de 10, avec un maximum à 1 000. Si vous devez parcourir tous les résultats d'une recherche, continuez tant que la réponse contient nextPageToken. Ne « fabriquez » pas un rang de départ en incrémentant : le curseur doit être réutilisé tel quel, tel que renvoyé par l'API.

Si votre traitement a besoin du total, activez countTotal=true. Cela aide à suivre la progression, mais ne remplace pas le jeton de pagination.

En production, documentez ce que vous logguez : nombre total, nombre de pages traitées, erreurs de requête. Ça permet d'attraper rapidement une collecte interrompue avant de publier des données partielles.

Exemple pratique en Python

Voici un exemple minimal en Python avec requests. Il récupère trois résultats, demande deux champs, puis extrait l'identifiant NCT depuis le nouveau chemin JSON.

import requests
base = "https://clinicaltrials.gov/api/v2/studies"
params = {
"query.term": "heart attack",
"fields": "NCTId,BriefTitle",
"pageSize": 3,
"countTotal": "true",
"sort": "@relevance",
}
response = requests.get(base, params=params, timeout=60)
response.raise_for_status()
data = response.json()
print("Nombre total :", data.get("totalCount"))
for study in data.get("studies", []):
identification = study.get("protocolSection", {}).get(
"identificationModule", {}
)
print(identification.get("nctId"))
next_token = data.get("nextPageToken")

Pour la page suivante, ajoutez pageToken=next_token aux paramètres et relancez. Dans une application réelle, mettez ça dans une boucle qui s'arrête quand le jeton disparaît. Et gardez une vraie gestion des erreurs : un souci réseau ne doit pas être interprété comme une « page vide ».

Vérifier le classement des résultats

Les deux versions peuvent renvoyer le même nombre d'études, mais pas forcément dans le même ordre. L'ancien système triait par pertinence ; v2 ne l'applique pas par défaut. Si l'ordre compte (pour une UI, pour des comparaisons, pour des tests), demandez explicitement sort=@relevance et comparez les premières lignes à un cas de référence.

C'est un test particulièrement utile en migration : une requête peut sembler « correcte » parce que le total correspond, alors que les résultats affichés en premier ont changé. Ne validez pas seulement les volumes : comparez aussi les identifiants, les champs essentiels et le comportement de tri.

Tableaux et valeurs d'énumération

En v2, les listes sont des tableaux simples, sans objets enveloppes supplémentaires. Beaucoup de champs sont au pluriel, comme conditions et phases. Si votre parseur attendait une structure précise (par exemple une imbrication « type XML » une étape plus haut), il peut échouer silencieusement ou ignorer des valeurs.

Côté énumérations, la représentation change aussi : des libellés comme « Recruiting » ou « Phase 2 » deviennent des codes comme RECRUITING et PHASE2. Pour relier libellés historiques et codes v2, utilisez /api/v2/studies/enums, qui fournit notamment legacyValue.

Évitez de faire une conversion « partielle » codée en dur si vos usages couvrent plusieurs statuts, phases ou types d'étude. Construire une table à partir des valeurs exposées par l'API est plus simple à maintenir. Et gardez séparément le libellé affiché (pour l'utilisateur) et le code utilisé pour filtrer (côté logique).

Dates et contenu riche

Les dates sont fournies en ISO 8601, avec une précision variable : année seule, mois, ou date complète (et parfois une heure). Des formes comme « June 2020 » ne correspondent donc plus à la même représentation. Certaines valeurs anciennement « inconnues » sont désormais décrites par des booléens, notamment SubmissionUnreleaseDateUnknown et UnpostedEventDateUnknown.

Ne forcez pas toutes les dates dans un format « jour » si la source ne donne qu'un niveau de granularité plus faible : vous inventeriez une précision. Dans une base ou une interface, conservez la valeur telle qu'elle existe, ou représentez explicitement la granularité disponible.

Le contenu enrichi est rendu en Markdown par défaut. Si un système existant dépend d'un formatage précis, le paramètre markupFormat=legacy peut aider à garder un comportement provisoire. Ça ne dispense pas de valider le rendu : HTML, XML ou texte brut ne traiteront pas forcément la même chaîne de la même façon.

Une stratégie de test raisonnable

Avant de basculer un flux de production, mettez en place un jeu de tests représentatif :

• une étude avec plusieurs phases ;
• une étude avec des résultats ;
• une étude avec des dates partielles ;
• une requête qui renvoie plusieurs pages.

Comparez les valeurs métier, pas juste la forme du JSON.

À minima, vérifiez :

• le nombre de résultats et les identifiants NCT attendus ;
• l'accès aux champs imbriqués et aux listes ;
• les codes d'énumération et leur correspondance avec les libellés affichés ;
• les dates partielles et les cas marqués comme inconnus ;
• la pagination jusqu'à ce qu'il n'y ait plus de nextPageToken ;
• le comportement du tri quand vous attendez un ordre particulier.

Quand le XML transitoire est-il pertinent ?

Diriger rapidement un ancien client vers /api/legacy/study-fields ou /api/legacy/full-studies peut être logique si vous priorisez la continuité de service, et si votre volume reste dans les limites annoncées.

Ça permet de découpler deux étapes : rétablir l'accès aux données, puis adapter progressivement le parseur vers la structure v2.

En revanche, c'est risqué si vous devez parcourir plus de 10 000 résultats, consommer de nouveaux champs, ou compter sur des évolutions de l'API. Et attention aussi aux versions : les endpoints legacy exposent leur propre version, distincte de celle indiquée par /api/v2/version. Ne supposez pas que la version XML reflète l'état de v2.

Choisir selon le coût de maintenance

Le critère décisif n'est pas « JSON vs XML ». C'est le coût total : temps d'adaptation du parseur, risque d'interruption, limites de volume, besoin de nouveaux champs, et capacité à tester correctement. Une passerelle legacy peut réduire le risque immédiat, mais si vous la gardez comme chemin principal pendant des mois, vous prolongez une dépendance à un format de compatibilité.