Documentação da API GEFRI

A API do Índice Global de Prontidão para os Futuros da Educação (GEFRI) oferece acesso aberto a dados por país e a resumos globais para que pesquisadores, desenvolvedores e formuladores de políticas possam analisar, comparar e baixar resultados atualizados do GEFRI. A API é pública e não exige autenticação.

Versão: 1.0   |   Formato: JSON

Início rápido: consultas de exemplo

• Obter todos os países (resumo global):

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

• Obter o perfil completo de Aruba (por código ISO3):

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

• Obter vários países por código:

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

• Obter todos os países da América Latina e Caribe, ordenados por pontuação (decrescente):

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

• Retornar apenas campos selecionados (código do país e pontuação composta):

  curl "https://gefri.educationfutures.com/api/gefri?fields=country code,score"

• Retornar apenas indicadores específicos de um país:

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

• Buscar um instantâneo histórico (dezembro de um determinado ano):

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

Uso básico e parâmetros de consulta

• Todos os países (padrão):
  /api/gefri
• Um único país por código ISO3:
  /api/gefri?code=FIN
• Vários países por código ISO3:
  /api/gefri?codes=FIN,USA,BRA
• Por região (sem distinção entre maiúsculas e minúsculas, com aliases como "LAC" ou "EAP"):
  /api/gefri?region=lac
• Ordenar resultados (o padrão é ordem decrescente para números):
  /api/gefri?sort=score&order=asc
• Retornar apenas campos específicos de nível superior:
  /api/gefri?fields=country name,score,region
• Obter campos com alias (shortnames):
  /api/gefri?shortnames=true
• Selecionar um instantâneo histórico (dezembro de um determinado ano):
  /api/gefri?year=2023

  Os arquivos históricos são armazenados por mês. Informe o ano para recuperar o instantâneo de dezembro desse ano; a API retorna 404 se o arquivo não estiver disponível.

Indicadores em nível de país

• Filtrar detalhes de indicadores (por código, separados por vírgula e sem distinção entre maiúsculas e minúsculas):
  /api/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• O array indicator_details é incluído apenas em resultados em nível de país.

Ordenação

• Ordenar por qualquer campo:
  /api/gefri?sort=score&order=desc
• Ordenar em ordem crescente:
  /api/gefri?sort=score&order=asc
• Ordenar alfabeticamente:
  /api/gefri?sort=Country Name&order=asc

Estrutura de resposta e tratamento de erros

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

Tratamento de erros: Se uma solicitação for inválida, a resposta inclui uma chave error com uma mensagem descritiva. Por exemplo:
{ "error": "Country code not found" }

Dicionário de dados

Cada objeto da API GEFRI inclui os seguintes campos. A disponibilidade pode variar. Todas as pontuações são normalizadas em uma escala de 0 a 100, salvo indicação em contrário. Population, total é usada apenas como série auxiliar e não entra em nenhuma pontuação GEFRI.

indicator_details (array, apenas por país): cada objeto contém:

Notas:
- indicator_details aparece apenas em resultados da API por país.
- data_source é sempre incluído para rastreabilidade.
- Os percentis são retornados como cadeias ordinais ("84th", "63rd"), não como números.

Aliases suportados

Use estes aliases para simplificar suas consultas.

Notas e atribuição

• Os dados são atualizados mensalmente. Os indicadores vêm de dados abertos, principalmente World Bank Open Data. World Bank Open Data.
• Ao usar o GEFRI em pesquisas ou aplicações, cite a Education Futures.
• Para feedback ou colaboração, entre em contato conosco. contato.