Documentación de la API de GEFRI

La API del Índice Global de Preparación para el Futuro de la Educación (GEFRI) ofrece acceso abierto a datos por país y resúmenes globales para que investigadores, desarrolladores y responsables de políticas puedan analizar, comparar y descargar resultados actualizados de GEFRI. La API es pública y no requiere autenticación.

Versión: v1   |   Formato: JSON

Inicio rápido: consultas de ejemplo

• Obtener todos los países (resumen global):

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

• Obtener el perfil completo de Aruba (por código ISO3):

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

• Obtener varios países por código:

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

• Obtener todos los países de América Latina y el Caribe, ordenados por puntuación (descendente):

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

• Devolver solo campos seleccionados de nivel superior:

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

• Devolver solo indicadores específicos de un país:

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

• Recuperar una instantánea histórica (diciembre de un año determinado):

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

Uso básico y parámetros de consulta

• Todos los países (predeterminado):
  /api/v1/gefri
• Un solo país por código ISO3 (code también acepta valores ISO3 separados por comas):
  /api/v1/gefri?code=FIN
• Varios países por código ISO3 (codes tiene prioridad sobre code):
  /api/v1/gefri?codes=FIN,USA,BRA
• Por región (sin distinguir mayúsculas y con alias como "LAC" o "EAP"):
  /api/v1/gefri?region=lac
• Ordenar resultados (por defecto, descendente para números):
  /api/v1/gefri?sort=score&order=asc
• Devolver solo campos específicos de nivel superior (coincidencia sin distinguir mayúsculas según el nombre real del campo):
  /api/v1/gefri?fields=Country Name,Country Code,Region
• Agregar campos con alias (shortnames) sin eliminar los nombres largos:
  /api/v1/gefri?shortnames=true
• Seleccionar una instantánea histórica (diciembre de un año determinado):
  /api/v1/gefri?year=2023

  Los archivos históricos se almacenan por mes. Especifique el año para recuperar la instantánea de diciembre de ese año; la API devuelve 404 si el archivo no está disponible.

Notas de comportamiento

• Si se proporciona code o codes, el modo country tiene prioridad incluso cuando level se omite o se establece en global. level=country sin códigos de país es inválido.
• Tanto code como codes aceptan valores ISO3 separados por comas. Cuando ambos aparecen, codes tiene prioridad.
• shortnames=true agrega RegionShort y alias cortos de componentes como score, access, innovation, human, governance e infra.
• El filtrado de campos coincide con claves de nivel superior sin distinguir mayúsculas y conserva indicator_details cuando esa matriz está presente.
• Todas las claves de respuesta que terminan en confidence se eliminan de forma recursiva antes de devolver la carga útil.

Indicadores a nivel de país

• Filtrar detalles de indicadores (por código, separados por comas y sin distinguir mayúsculas):
  /api/v1/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• indicator_details solo aparece en resultados a nivel de país y se conserva incluso cuando se aplica filtrado de fields.

Ordenación

• Ordenar por cualquier campo:
  /api/v1/gefri?sort=score&order=desc
• Orden ascendente:
  /api/v1/gefri?sort=score&order=asc
• Orden alfabético:
  /api/v1/gefri?sort=Country Name&order=asc

Estructura de respuesta y manejo de errores

{
  "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...
    ]
  }
}

Manejo de errores: Si una solicitud es inválida, la respuesta incluye una clave error con un mensaje descriptivo. Por ejemplo:
{ "apiVersion": "1", "error": "Invalid request." }

Cuando coincide exactamente un país, data se devuelve como objeto. Cuando coinciden varios países, data se devuelve como matriz. Los archivos de países ausentes se omiten, por lo que los códigos sin coincidencia pueden devolver count 0 en lugar de 404.

Diccionario de datos

Cada objeto de la API de GEFRI incluye los siguientes campos. La disponibilidad puede variar. Todas las puntuaciones están normalizadas en una escala de 0 a 100, salvo que se indique lo contrario. Population, total se utiliza solo como serie auxiliar y no interviene en ninguna puntuación de GEFRI.

indicator_details (matriz, solo por país): cada objeto contiene:

Notas:
- indicator_details solo aparece en resultados de API por país.
- data_source siempre se incluye para la trazabilidad.
- Los percentiles se devuelven como cadenas ordinales ("84th", "63rd"), no como números.

Alias compatibles

Utilice estos alias para simplificar sus consultas.

Notas y atribución

• Los datos se actualizan mensualmente. Los indicadores provienen de datos abiertos, principalmente World Bank Open Data. World Bank Open Data.
• Cuando utilice GEFRI en investigación o aplicaciones, cite a Education Futures.
• Para comentarios o colaboración, contáctenos. contacto.