Recherche et requête openFDA

Prérequis

uv: Lisez la compétence uv et suivez ses instructions de configuration pour vous assurer que uv est installé et accessible dans PATH.
Notification utilisateur: Si LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de cette compétence, alors (1) notifiez l'utilisateur de vérifier les conditions à https://open.fda.gov/apis/ et https://open.fda.gov/license, puis (2) créez le fichier en enregistrant le texte de notification et l'horodatage.
Fichier .env: Assurez-vous que le fichier .env existe dans votre répertoire home. Créez-en un s'il n'existe pas.
FDA_API_KEY (optionnel mais recommandé): Augmente la limite de requêtes quotidiennes de 1 000 à 120 000. La compétence fonctionne sans elle, mais un agent peut facilement épuiser la limite sans clé en une seule session. L'utilisateur peut s'inscrire pour une clé gratuite à https://open.fda.gov/apis/authentication/. Si la variable est manquante dans .env, ne demandez PAS à l'utilisateur de la coller dans le chat (cela fuirait la clé dans le contexte de l'agent). À la place, donnez à l'utilisateur cette commande — en remplaçant ENV_FILE par le chemin littéral résolu vers le fichier .env:
```
printf "Enter openFDA API key (typing hidden): " && read -s key && echo && echo "FDA_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
```
Les scripts chargent automatiquement les identifiants via dotenv. Ne JAMAIS lire, afficher ou inspecter le fichier .env ou ses variables (par exemple, pas de cat, grep, echo, printenv ou os.environ.get sur les clés). Les identifiants doivent rester en dehors du contexte de l'agent.

Règles fondamentales

Utiliser le wrapper: TOUJOURS exécuter les scripts d'assistance fournis pour interroger la base de données au lieu d'y accéder directement. Les scripts appliquent automatiquement les limites de débit requises avec grâce.
Limitation du débit: Respectez les limites de débit openFDA. Sans clé API: 240 requêtes/min, 1 000 requêtes/jour par IP. Avec clé API: 240 requêtes/min, 120 000 requêtes/jour par clé. Définissez toujours une clé API avant d'exécuter des workflows multi-requêtes.

Avertissement: Un agent automatisé peut facilement épuiser la limite quotidienne de 1 000 requêtes en une seule session de recherche. Définissez toujours une clé API avant d'exécuter des workflows multi-requêtes.

Instruisez l'utilisateur de s'inscrire pour une clé gratuite à https://open.fda.gov/apis/authentication/ et suivez les instructions de prérequis ci-dessus pour ajouter FDA_API_KEY au fichier .env. Le script émettra un avertissement vers stderr si aucune clé API n'est détectée.

Toujours utiliser --output: Toutes les sous-commandes nécessitent --output <file> pour écrire les résultats dans un fichier. Cela empêche que les grandes sorties deviennent écrasantes. Utilisez jq ou du code pour lire le fichier de sortie.
Notification: Si cette compétence est utilisée, assurez-vous que cela est mentionné dans la sortie.

Script utilitaire

Script unique pour toutes les opérations:

uv run scripts/openfda_query.py {search,count,download} --output <file> [options]

1. Search

Recherchez l'un des 28 endpoints et enregistrez les résultats JSON dans un fichier.

uv run scripts/openfda_query.py search \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --limit 5 --output /tmp/fda_results.json

Stdout affiche un résumé compact:

{"status": "success", "output": "/tmp/fda_results.json", "results_in_file": 5, "total_matching": 601477}

Options:

--output: Fichier de sortie pour les résultats JSON complets (obligatoire).
--category: Catégorie API — drug, device, food, tobacco, other, animalandveterinary, cosmetic, transparency.
--endpoint: Endpoint dans la catégorie (par exemple, event, label, 510k). Voir references/api_endpoints.md pour la liste complète.
--search: Chaîne de requête (par exemple, patient.drug.medicinalproduct:aspirin+AND+serious:1).
--sort: Champ de tri et ordre (par exemple, receivedate:desc).
--limit: Résultats maximum (défaut 10, max 1 000).
--skip: Décalage de pagination (défaut 0).
--api_key: Clé API (lit également la variable d'environnement FDA_API_KEY).

2. Count

Comptez les valeurs uniques d'un champ dans les résultats correspondants.

uv run scripts/openfda_query.py count \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --count_field "patient.reaction.reactionmeddrapt.exact" \
  --summary 10 --output /tmp/aspirin_reactions.json

Stdout affiche un résumé avec les 5 premiers termes. Les données complètes se trouvent dans le fichier de sortie.

Options supplémentaires:

--count_field: Champ à compter (ajoutez .exact pour compter des phrases complètes).
--summary N: Retourne uniquement les N termes les plus fréquents. Utilisez-le pour éviter d'inonder le contexte avec des centaines de termes peu fréquents.

3. Download

Téléchargez plusieurs pages de résultats dans un fichier.

uv run scripts/openfda_query.py download \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:aspirin" \
  --limit 100 --max_pages 5 \
  --output /tmp/aspirin_events.json

Options supplémentaires:

--max_pages: Pages maximum à récupérer (défaut 10).
--all_results: Paginez automatiquement pour récupérer tous les résultats correspondants. Limite de sécurité de 25 000 enregistrements maximum par téléchargement pour prévenir les téléchargements incontrôlés et une utilisation API excessive.

Astuce: Les médicaments courants peuvent avoir des rapports excessifs. Utilisez une plage de dates (par exemple, receivedate:[20250101+TO+20250131]) pour limiter le volume de téléchargement.

Résolution d'entités: Utiliser .exact pour la précision

Lors de la recherche de noms de produits spécifiques, de noms de médicaments ou de termes catégoriques, utilisez toujours le suffixe .exact sur le champ pour obtenir des résultats correspondant exactement. Sans cela, l'API segmente les valeurs multi-mots et retourne des correspondances partielles bruyantes.

# Précis: ne correspond qu'à "ADVIL"
uv run scripts/openfda_query.py search --category drug --endpoint label \
  --search 'openfda.brand_name.exact:"ADVIL"' \
  --limit 5 --output /tmp/advil_label.json

Note: De nombreux noms de marques dans la base de données FDA incluent des suffixes de variantes (par exemple, "TYLENOL Extra Strength" plutôt que juste "TYLENOL"). Si une recherche .exact retourne 0 résultats, essayez sans .exact pour voir les variantes de noms de marques disponibles, puis relancez la requête avec le nom exact complet.

Le suffixe .exact est également requis lors de l'utilisation de --count_field pour agréger des phrases complètes au lieu de mots individuels.

Résolution de termes MedDRA

Les données d'événements indésirables openFDA utilisent les termes MedDRA (Medical Dictionary for Regulatory Activities) pour les réactions. L'API rapporte les Preferred Terms (PTs) mais ne fournit pas la hiérarchie MedDRA (System Organ Class, High Level Terms, etc.).

Note: MedDRA est une ontologie propriétaire et n'est pas indexée dans EMBL-EBI OLS. Pour approximer les recherches de hiérarchie MedDRA, utilisez l'ontologie des phénotypes humains (HP) ou le vocabulaire NCI (NCIT) comme ontologies proxy — elles font référence croisée aux ID MedDRA et fournissent des relations parent/ancêtre.

# Étape 1: Obtenir les principales réactions d'openFDA
uv run scripts/openfda_query.py count \
  --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:metformin" \
  --count_field "patient.reaction.reactionmeddrapt.exact" \
  --summary 5 --output /tmp/metformin_reactions.json

# Étape 2: Recherchez le principal terme de réaction en utilisant un service
# d'ontologie biomédicale (par exemple, compétence embl-ebi-ols).
# MedDRA n'est pas disponible dans OLS; utilisez l'ontologie des phénotypes
# humains (HP) ou le vocabulaire NCI (NCIT) comme proxy pour trouver la
# classification hiérarchique du terme de réaction.

Endpoints disponibles (28 au total)

Correspondance catégorie vers endpoint:

drug: event, label, ndc, enforcement, drugsfda, shortages
device: 510k, classification, enforcement, event, pma, recall, registrationlisting, udi, covid19serology
food: enforcement, event
tobacco: problem, researchpreventionads, researchdigitalads, researchsmokefree
other: historicaldocument, nsde, substance, unii
animalandveterinary: event
cosmetic: event
transparency: crl

Référence

Syntaxe de requête et tous les endpoints: Voir references/api_endpoints.md pour les noms de champs, la syntaxe de recherche, les plages de dates et les opérateurs booléens.

Recettes

Modèles de requête courants pour les médicaments, appareils, aliments, tabac, cosmétiques, produits animaux et vétérinaires, substances, données de transparence, événements indésirables, rappels, étiquetage, approbations, pénuries, autorisations 510(k), recherches NDC, toute requête sur les données de sécurité ou réglementaires de la FDA, et bien d'autres. Voir references/recipes.md pour les recettes complètes.

Workflow

Recherchez des enregistrements en utilisant search avec --output. Lisez le fichier de sortie.
Utilisez count avec --summary 10 --output pour résumer les distributions de champs.
Utilisez download (avec --all_results pour les extractions exhaustives) pour récupérer des ensembles de données plus importants.
Lisez et analysez le fichier de sortie en utilisant des outils standard.
Pour les questions sur la hiérarchie des termes MedDRA, utilisez une compétence de service d'ontologie biomédicale (par exemple, compétence EMBL-EBI OLS avec l'ontologie HP ou NCIT) pour rechercher le terme.

openfda-database