Comment passer de l’API iati.cloud à la version 3 de l’API de la banque de données de l’IITA
Conseils destinés aux utilisateurs de l’API iati.cloud souhaitant passer à la version 3 de l’API de la banque de données de l’IITA
La version 3 de l’API de la banque de données de l’IITA repose sur la même technologie que l’API SOLR utilisée dans iati.cloud. Plusieurs optimisations ont toutefois été apportées afin que toutes les données valides soient extraites et que les résultats soient conformes au schéma de l’IITA. Vous trouverez sur cette page une comparaison entre les deux API.
Attention : iati.cloud n’est plus géré par l’IITA et ne propose plus nécessairement les mêmes services qu’auparavant.
Migration étape par étape
Pour reproduire une requête effectuée sur iati.cloud sans y ajouter de fonctions de recherche avancées, la marche à suivre est la suivante :
Créer un compte sur le portail API
Tous les utilisateurs de la version 3 de l’API de la banque de données de l’IITA doivent s’inscrire sur le portail API de l’Initiative pour obtenir une clé API gratuite. Cette étape permet au Secrétariat de l’IITA de mieux suivre l’utilisation des API de l’Initiative et d’assurer un service fiable et sécurisé aux utilisateurs. Une fois connecté au portail API, vous avez le choix entre deux types d’inscription :
| Année | Description |
|---|---|
| Exploratory (Exploration) | Possibilité d’effectuer 5 appels/minute et jusqu’à 100 appels/semaine. Aucune approbation nécessaire pour l’inscription. |
| Full Access (Accès illimité) | Accès illimité aux API publiques. |
Une fois l’inscription terminée, vous pourrez utiliser les clés API mises à votre disposition, soit en ligne à partir du portail API, soit en local à partir de vos outils de développement. Vous trouverez de plus amples informations dans les instructions relatives au portail API.
Changer l’URL de base
| iati.cloud | Version 3 de la banque de données de l’IITA |
|---|---|
| https://datastore.iati.cloud/api/v2/activity? | https://api.iatistandard.org/datastore/activity/select? |
| https://datastore.iati.cloud/api/v2/transaction? | https://api.iatistandard.org/datastore/transaction/select? |
| https://datastore.iati.cloud/api/v2/budget? | https://api.iatistandard.org/datastore/budget/select? |
Sélectionner les champs de données à extraire
Avec l’API d’iati.cloud, les recherches portant sur les transactions et les budgets ne renvoyaient qu’un certain nombre de champs disponibles dans les données de l’IITA. La version 3 de l’API, en revanche, renvoie l’intégralité des champs disponibles. Il est possible d’utiliser le paramètre « fl= » pour limiter les champs renvoyés, de façon à ce que les résultats correspondent à ceux renvoyés par iati.cloud.
| iati.cloud | Sélection des champs dans la version 3 de l’API de la banque de données de l’IITA |
|---|---|
| https://datastore.iati.cloud/api/v2/transaction? | &fl=iati_identifier,reporting_org_ref,title_narrative,description_narrative,recipient_country_code,recipient_region_code,sector_code,transaction_ref,transaction_humanitarian,transaction_transaction_type_code,transaction_transaction_date_iso_date,transaction_value_currency,transaction_value_value_date,transaction_value,transaction_provider_org_ref,transaction_provider_org_provider_activity_id,transaction_provider_org_type,transaction_provider_org_narrative,transaction_receiver_org_ref,transaction_receiver_org_receiver_activity_id,transaction_receiver_org_type,transaction_receiver_org_narrative,transaction_disbursement_channel_code,transaction_sector_vocabulary,transaction_sector_code,transaction_recipient_country_code,transaction_recipient_region_code,transaction_flow_type_code,transaction_finance_type_code,transaction_aid_type_code,transaction_aid_type_vocabulary,transaction_tied_status_code,transaction_description_narrative,default_currency,xml_lang,default_flow_type_code,default_aid_type_code,default_tied_status_code,humanitarian |
| https://datastore.iati.cloud/api/v2/budget? | &fl=iati_identifier,reporting_org_ref,reporting_org_type,recipient_country_code,recipient_country_narrative,budget_type,budget_status,budget_period_start_iso_date,budget_period_end_iso_date,budget_value_currency,budget_value_value_date,budget_value,default_currency,xml_lang,default_flow_type_code,default_tied_status_code,default_aid_type_code,humanitarian |
Changer les noms des champs dans les paramètres de requête
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 :
| Noms IITA | Noms dans la version 3 de la banque de données de l’IITA |
|---|---|
| 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.
Les champs dont le nom n’est pas le même dans iati.cloud et dans la version 3 de la banque de données de l’IITA sont les suivants :
| Noms dans iati.cloud | Noms dans la version 3 de la banque de données de l’IITA |
|---|---|
| default_lang | xml_lang |
| reporting_org_type_code | reporting_org_type |
| location_id_code | location_location_id_code |
| location_id_vocabulary | location_location_id_vocabulary |
| location_reach_code | location_location_reach_code |
| location_class_code | location_location_class_code |
| country_budget_items_budget_description_narrative_lang | country_budget_items_budget_item_description_narrative_xml_lang |
| country_budget_items_budget_description_narrative_text | country_budget_items_budget_item_description_narrative |
| planned_disbursement_value_date | planned_disbursement_value_value_date |
| planned_disbursement_provider_org_narrative_lang | planned_disbursement_provider_org_narrative_xml_lang |
| planned_disbursement_provider_org_narrative_text | planned_disbursement_receiver_org_narrative |
| transaction_type | transaction_transaction_type_code |
| transaction_date_iso_date | transaction_transaction_date_iso_date |
| transaction_value_date | transaction_value_value_date |
| transaction_provider_org_narrative_lang | transaction_provider_org_narrative_xml_lang |
| transaction_provider_org_narrative_text | transaction_provider_org_narrative |
| location_id_code | location_location_id_code |
| transaction_disburstment_channel_code | transaction_disbursement_channel_code |
| result_indicator_title_narrative_lang | result_indicator_title_narrative_xml_lang |
| result_indicator_title_narrative_text | result_indicator_title_narrative |
| result_indicator_description_narrative_lang | result_indicator_description_narrative_xml_lang |
| result_indicator_description_narrative_text | result_indicator_description_narrative |
| result_indicator_reference_vocabulary_uri | result_indicator_reference_indicator_uri |
| result_indicator_baseline_comment_narrative_lang | result_indicator_baseline_comment_narrative_xml_lang |
| result_indicator_baseline_comment_narrative_text | result_indicator_baseline_comment_narrative |
| result_indicator_period_target_comment_narrative_lang | result_indicator_period_target_comment_narrative_xml_lang |
| result_indicator_period_target_comment_narrative_text | result_indicator_period_target_comment_narrative |
| result_indicator_period_actual_comment_narrative_lang | result_indicator_period_actual_comment_narrative_xml_lang |
| result_indicator_period_actual_comment_narrative_text | result_indicator_period_actual_comment_narrative |
| result_document_link_title_narrative_lang | result_document_link_title_narrative_xml_lang |
| result_document_link_title_narrative_text | result_document_link_title_narrative |
| result_document_link_description_narrative_lang | result_document_link_description_narrative_xml_lang |
| result_document_link_description_narrative_text | result_document_link_description_narrative |
| result_indicator_document_link_title_narrative_lang | result_indicator_document_link_title_narrative_xml_lang |
| result_indicator_document_link_title_narrative_text | result_indicator_document_link_title_narrative_text |
Sélectionner les résultats à extraire
La version 3 de l’API permet d’extraire au maximum 1 000 documents à la fois, de façon à ce que la taille des fichiers soit supportée par la plupart des navigateurs et que les données soient renvoyées dans des délais raisonnables.
Comme dans iati.cloud, le nombre de documents à extraire est défini à l’aide du paramètre « rows » (lignes). Pour extraire tous les documents correspondant à une même requête, les utilisateurs devront renvoyer l’appel API à plusieurs reprises pour passer en revue toutes les pages disponibles à l’aide du paramètre « start » (début). Par exemple :
- Pour obtenir les 1 000 premiers documents : &rows=1000&start=1
- Pour obtenir les 1000 documents suivants : &rows=1000&start=1001
Résultats ne pouvant pas être extraits
La version 3 de l’API de la banque de données de l’IITA ne possède pas de fonctionnalité intégrée permettant de convertir les devises en dollars US. Les utilisateurs devront donc utiliser la date de valeur des transactions financières et convertir les devises à l’aide de la méthode de leur choix. iati.cloud utilisait le taux de conversion moyen du FMI pour un mois donné.
Les points d’extrémité suivants, uniquement valables pour des résultats au format CSV, ne possèdent pas d’équivalent dans la version 3 de l’API :
- https://datastore.iati.cloud/api/v2/activity-sector?
- https://datastore.iati.cloud/api/v2/activity-country?
Comparaison de la version 3 de l’API de la banque de données de l’IITA et de l’API d’iati.cloud
Les deux API ont une architecture très similaire. Cependant, la version 3 de l’API de la banque de données est conçue pour offrir plus de flexibilité aux utilisateurs dans le filtrage des données. Toutes les données de l’IITA peuvent notamment être interrogées et extraites par activité, par transaction ou par budget.
De plus, la version 3 de l’API effectue des mises à jour plus régulières, revient moins cher et est soumise à un contrat d’API.
Attention : la banque de données de l’IITA ne procède à aucun traitement des données de l’IITA. Tout travail post-traitement (conversion de devises, ventilation par pays/région/secteur, etc.) interviendra en aval et sera pris en compte dans les futurs travaux de l’IITA.
| Version 3 de la banque de données de l’IITA | iati.cloud |
|---|---|
| Clé d’inscription API obligatoire | Pas de clé d’inscription requise |
| Toutes les données de l’IITA peuvent être interrogées et extraites pour chaque point d’extrémité | Seules certaines données de l’IITA peuvent être interrogées pour chaque point d’extrémité |
| Toutes les données de l’IITA peuvent être extraites pour chaque point d’extrémité | Seules certaines données de l’IITA peuvent être extraites pour chaque point d’extrémité |
| Tous les noms de champs sont conformes à la norme de l’IITA | Tous les noms de champs ne sont pas conformes à la norme de l’IITA |
| Recherche de texte libre disponible pour tous les éléments <narrative> | Recherche de texte libre disponible uniquement pour certains éléments <narrative> |
| Mise en forme des résultats | Pas de mise en forme des résultats |
| Pas de conversion des devises en dollars US | Conversion de certaines devises en dollars US |
| Pas de ventilation par secteur d’activité ou par pays dans les résultats au format CSV | Possibilité d’afficher les résultats au format CSV avec un pays ou un secteur par ligne |
Assistance
La banque de données de l’IITA a été conçue par le Secrétariat de l’IITA. Si vous avez besoin d’une aide supplémentaire pour passer à la nouvelle API ou pour l’utiliser, contactez le service d’assistance de l’IITA à l’adresse suivante :[email protected]. Le Secrétariat de l’IITA se fera un plaisir de vous appeler pour vous aider à prendre en main cet outil.