Comment utiliser l’API de la banque de données
Découvrez comment créer des requêtes pour la version 3 de l’API de la banque de données et extraire des données de l’IITA afin de les analyser.
Date de publication par l’équipe technique de l’IITA : 11 janvier 2022
Ce guide explique la marche à suivre pour créer des requêtes dans la version 3 de l’API de la banque de données. Vous trouverez ci-dessous quelques-unes des fonctionnalités et des options de cette nouvelle API. Une liste complète des fonctionnalités que l’IITA s’engage à conserver figure dans le contrat d’API. Toutes les fonctionnalités qui relèvent de la documentation de la plateforme SOLR peuvent être utilisées via la version 3 de l’API, mais ne figurent pas dans le contrat d’API de l’IITA, car elles sont susceptibles d’être modifiées ou mises à jour au fil du temps.
- Contrat d’API pour la version 3 de la banque de données : ce contrat contient la liste complète des options de recherche et de filtrage que l’IITA s’engage à conserver dans la version 3 de l’API. Les principales fonctionnalités sont décrites ci-dessous.
- Documentation de la plateforme SOLR : contient toutes les fonctionnalités disponibles via SOLR. La liste des fonctionnalités disponibles via SOLR est plus longue que celle des fonctionnalités que l’IITA s’engage à conserver dans la version 3 de l’API.
L’API de la banque de données est accessible via le portail API de l’IITA. Consultez la page relative au portail API pour de plus amples informations.
Des exemples d’appels API complexes sont disponibles ici.
Chaque utilisateur doit disposer d’un compte gratuit et saisir sa clé d’inscription pour créer des requêtes. La suite de l’article explique comment créer des requêtes API, mais également comment le faire à l’aide de la barre de requête du portail API.
Attention : pour utiliser la banque de données de l’IITA, les utilisateurs devront tout d’abord disposer des compétences techniques nécessaires et comprendre la structure et les éléments fondamentaux de la norme de l’IITA. D’autres manières d’accéder aux données de l’IITA sont présentées dans les Outils et ressources relatifs à l’utilisation des données de l’IITA.
Points d’extrémité disponibles
Les données extraites peuvent être formatées de trois manières différentes, chaque ligne pouvant représenter une activité, une transaction ou un budget. Chaque point d’extrémité renvoie toutes les données d’activités qui correspondent à l’activité, à la transaction ou au budget en question.
- https://api.iatistandard.org/datastore/activity/select?
- https://api.iatistandard.org/datastore/transaction/select?
- https://api.iatistandard.org/datastore/budget/select?
Dans la barre de requête, utilisez le paramètre « collection », et sélectionnez « activity » (activité), « transaction » (transaction) ou « budget » (budget) dans la liste déroulante :
| Paramètre | Valeur |
|---|---|
| collection | « activity » (activité) |
Comment ajouter des filtres de recherche d’activités
Pour ajouter le premier filtre, on utilise la séquence « q= », à laquelle on pourra ajouter d’autres filtres en utilisant les commandes « AND » (ET), « OR » (OU), « NOT » (SANS) et « + » (qui signifie ET/OU, que l’on ne peut exprimer par du texte).
Recherches par codes d’attribut
- Rechercher un code d’attribut spécifique : q=sector_code:11110
- Rechercher plusieurs codes d’attribut : q=recipient_country_code:(UG TZ)
- Rechercher un code OU un autre : q=sector_code:11110 OR transaction_sector_code:11110
- Rechercher un code ET un autre : q=recipient_country_code:UG AND sector_code:11110
- Rechercher un code ET/OU un autre : q=recipient_country_code:UG + sector_code:11110
- Rechercher un code mais PAS un autre : q=recipient_country_code:UG NOT sector_code:11110
Recherches de texte libre
- Recherche de texte libre dans un élément <narrative> spécifique : q=description_narrative:rabbit
- Recherche de texte libre dans plusieurs éléments <narrative> : q=title_narrative:rabbit OR description_narrative:rabbit OR iati_identifier:rabbit OR transaction_description_narrative:rabbit
- Recherche de deux mots dans un élément <narrative> spécifique : q=title_narrative:(rabbit AND production)
- Recherche d’expression dans un élément <narrative> spécifique : q=title_narrative:“rabbit production”
Remarque : l’identifiant de l’IITA est considéré comme un élément <narrative> (texte libre) dans la banque de données de l’IITA. Pour trouver une activité spécifique, utilisez des guillemets : par exemple, q=iati_identifier:“US-GOV-1-AID-OAA-TO-14-00001”
Options complémentaires pour les recherches par élément <narrative>
- * = caractère générique, pour obtenir les correspondances avec aucune autre lettre ou n’importe quelle suite de lettres
Par exemple, pomme* renvoie pomme, pommes et pommeau
- ? = un seul caractère, pour obtenir les correspondances pour n’importe quel caractère unique
Par exemple, s?l renvoie sol et sel
Remarque : si l’on utilise les caractères génériques * ou ? dans une recherche de texte libre, le terme recherché NE DOIT PAS être mis entre guillemets. Si l’on utilise des guillemets, les symboles * et ? seront recherchés tels quels dans le texte.
Comment rechercher des dates et des valeurs monétaires
L’API permet aux utilisateurs de sélectionner des dates et des valeurs monétaires comprises dans une certaine fourchette. On utilise pour cela l’opérateur [* TO *].
- q=transaction_value:[* TO 10000] renvoie toutes les valeurs inférieures à égales à 10 000 pour ce champ.
- q=activity_date_iso_date:[2021-01-01T00:00:00Z TO *] recherche toutes les activités dont la date d’activité est ultérieure au 1er janvier 2021.
Remarque : l’API SOLR ne peut pas rechercher à la fois le type et la date iso dans un même élément relatif à la date d’activité. Vous ne pouvez donc pas sélectionner uniquement une date de début ou de fin ; cette manipulation devra être effectuée par l’utilisateur ou par le programme une fois les résultats obtenus au format JSON, XML ou CSV.
Dans la barre de requête, utilisez le paramètre « q » puis ajoutez la combinaison de filtres souhaitée à l’aide des conseils ci-dessous. Exemple :
| Paramètre | Valeur |
|---|---|
| q | title_narrative:(rabbit AND production) |
Extraire des colonnes spécifiques
- &fl=description_narrative,sector_code
Dans la barre de requête, utilisez le paramètre « fl » puis ajoutez la liste de champs de données à extraire. Exemple :
| Paramètre | Valeur |
|---|---|
| fl | description_narrative,sector_code |
Comment sélectionner le format
- &wt=json
- &wt=xml
- &wt=csv
Dans la barre de requête, utilisez le paramètre « wt » et choisissez parmi les trois options suivantes : json, xml ou csv.
| Paramètre | Valeur |
|---|---|
| wt | json |
Comment sélectionner le nombre de lignes
Si cette option n’est pas utilisée, 10 résultats seront extraits par défaut.
Chaque appel API permet d’extraire 1 000 lignes au maximum. Utilisez le paramètre « &start » pour choisir à partir de quelle ligne vous souhaitez commencer.
- &rows=50
- &start=0
Dans la barre de requête, utilisez les paramètres « rows » et « start », puis indiquez le nombre souhaité. Exemple :
| Paramètre | Valeur |
|---|---|
| rows | 50 |
| start | 0 |
Noms des éléments/attributs
Les noms des éléments et des attributs sont fondés sur les noms et le chemin d’accès fournis dans le schéma de l’IITA. Chaque séquence de caractères non alphabétiques est remplacée par le symbole « _ ».
Par exemple :
| Nom IITA | Nom dans l’API |
|---|---|
| iati-identifier | iati_identifier |
| transaction/value | transaction_value |
| transaction/value/@currency | transaction_value_currency |
| transaction/description/narrative/@xml:lang | transaction_description_narrative_xml_lang |
Une liste complète des noms, des chemins d’accès ainsi que du type de données pour chaque élément et attribut est disponible dans le tableau récapitulatif des activités.
Encodage des caractères
L’API encode certains caractères. Lorsque vous saisissez ou collez une commande dans une API, vous pouvez utiliser soit le caractère habituel, soit son code. Par exemple :