Documentation de l’API GEFRI

L’API de l’Indice mondial de préparation aux futurs de l’éducation (GEFRI) donne un accès ouvert aux données par pays et aux synthèses mondiales afin que les chercheurs, développeurs et décideurs puissent analyser, comparer et télécharger des résultats GEFRI à jour. L’API est publique et ne nécessite aucune authentification.

Version: v1   |   Format: JSON

Démarrage rapide : requêtes d’exemple

• Obtenir tous les pays (résumé mondial) :

  curl https://gefri.educationfutures.com/api/v1/gefri

• Obtenir le profil complet d’Aruba (par code ISO3) :

  curl https://gefri.educationfutures.com/api/v1/gefri?code=ABW

• Obtenir plusieurs pays par code :

  curl "https://gefri.educationfutures.com/api/v1/gefri?codes=USA,FIN,BRA"

• Obtenir tous les pays d’Amérique latine et des Caraïbes, triés par score (décroissant) :

  curl "https://gefri.educationfutures.com/api/v1/gefri?region=lac&sort=score&order=desc"

• Ne renvoyer que certains champs de premier niveau :

  curl "https://gefri.educationfutures.com/api/v1/gefri?fields=Country Code,Country Name,Composite GEFRI Score"

• Ne renvoyer que des indicateurs spécifiques pour un pays :

  curl "https://gefri.educationfutures.com/api/v1/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS"

• Récupérer un instantané historique (décembre d’une année donnée) :

  curl "https://gefri.educationfutures.com/api/v1/gefri?year=2023&codes=FIN,SWE"

Utilisation de base et paramètres de requête

• Tous les pays (par défaut) :
  /api/v1/gefri
• Un seul pays par code ISO3 (code accepte aussi des valeurs ISO3 séparées par des virgules) :
  /api/v1/gefri?code=FIN
• Plusieurs pays par code ISO3 (codes prend le pas sur code) :
  /api/v1/gefri?codes=FIN,USA,BRA
• Par région (insensible à la casse, avec alias comme "LAC" ou "EAP") :
  /api/v1/gefri?region=lac
• Trier les résultats (par défaut, ordre décroissant pour les nombres) :
  /api/v1/gefri?sort=score&order=asc
• Ne renvoyer que certains champs de premier niveau (correspondance insensible à la casse sur le nom réel du champ) :
  /api/v1/gefri?fields=Country Name,Country Code,Region
• Ajouter des champs aliasés (shortnames) sans retirer les noms longs :
  /api/v1/gefri?shortnames=true
• Sélectionner un instantané historique (décembre d’une année donnée) :
  /api/v1/gefri?year=2023

  Les archives historiques sont stockées par mois. Indiquez l’année pour récupérer l’instantané de décembre correspondant ; l’API renvoie 404 si l’archive n’est pas disponible.

Notes de comportement

• Si code ou codes est fourni, le mode country prend le pas même lorsque level est omis ou défini sur global. level=country sans code pays est invalide.
• code et codes acceptent tous deux des valeurs ISO3 séparées par des virgules. Lorsque les deux sont présents, codes a priorité.
• shortnames=true ajoute RegionShort ainsi que des alias courts de composants comme score, access, innovation, human, governance et infra.
• Le filtrage fields correspond aux clés de premier niveau sans tenir compte de la casse et conserve indicator_details lorsque ce tableau est présent.
• Toutes les clés de réponse se terminant par confidence sont supprimées récursivement avant le renvoi de la charge utile.

Indicateurs au niveau pays

• Filtrer les détails des indicateurs (par code, séparés par des virgules, insensibles à la casse) :
  /api/v1/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• indicator_details n’apparaît que dans les résultats au niveau pays et est conservé même lorsque le filtrage fields est appliqué.

Tri

• Trier par n’importe quel champ :
  /api/v1/gefri?sort=score&order=desc
• Tri croissant :
  /api/v1/gefri?sort=score&order=asc
• Tri alphabétique :
  /api/v1/gefri?sort=Country Name&order=asc

Structure de réponse et gestion des erreurs

{
  "apiVersion": "1",
  "level": "country",
  "snapshot": "current",
  "count": 1,
  "data": {
    "Country Name": "Aruba",
    "Country Code": "ABW",
    "Region": "Latin America & Caribbean",
    "Composite GEFRI Score": 67.8,
    // ...other fields...
    "indicator_details": [
      {
        "indicator_code": "SP.POP.TOTL",
        "indicator_name": "Population, total",
        "component": null,
        "year": 2023,
        "reported_value": 41454761,
        "data_source": "World Bank",
        "normalized_value": null,
        "global_percentile": null,
        "regional_percentile": null,
        "notes": ""
      }
      // ...etc...
    ]
  }
}

Gestion des erreurs : Si une requête est invalide, la réponse inclut une clé error avec un message descriptif. Par exemple :
{ "apiVersion": "1", "error": "Invalid request." }

Lorsqu’un seul pays correspond, data est renvoyé comme objet. Lorsque plusieurs pays correspondent, data est renvoyé comme tableau. Les fichiers pays manquants sont ignorés ; des codes non trouvés peuvent donc renvoyer count 0 au lieu de 404.

Dictionnaire de données

Chaque objet de l’API GEFRI comprend les champs suivants. La disponibilité peut varier. Tous les scores sont normalisés sur une échelle de 0 à 100, sauf indication contraire. Population, total n’est utilisée que comme série auxiliaire et n’entre dans aucun score GEFRI.

indicator_details (tableau, par pays uniquement) : chaque objet contient :

Notes :
- indicator_details n’apparaît que dans les résultats API par pays.
- data_source est toujours inclus pour assurer la traçabilité.
- Les percentiles sont renvoyés sous forme de chaînes ordinales ("84th", "63rd"), et non de nombres.

Alias pris en charge

Utilisez ces alias pour simplifier vos requêtes.

Notes et attribution

• Les données sont mises à jour chaque mois. Les indicateurs proviennent de données ouvertes, principalement World Bank Open Data. World Bank Open Data.
• Lorsque vous utilisez GEFRI dans des recherches ou des applications, veuillez citer Education Futures.
• Pour tout retour ou collaboration, contactez-nous. contact.