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: v1   |   Formato: JSON

Início rápido: consultas de exemplo

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

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

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

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

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

  curl "https://gefri.educationfutures.com/api/v1/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/v1/gefri?region=lac&sort=score&order=desc"

• Retornar apenas campos selecionados de nível superior:

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

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

  curl "https://gefri.educationfutures.com/api/v1/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/v1/gefri?year=2023&codes=FIN,SWE"

Uso básico e parâmetros de consulta

• Todos os países (padrão):
  /api/v1/gefri
• Um único país por código ISO3 (code também aceita valores ISO3 separados por vírgulas):
  /api/v1/gefri?code=FIN
• Vários países por código ISO3 (codes tem prioridade sobre code):
  /api/v1/gefri?codes=FIN,USA,BRA
• Por região (sem distinção entre maiúsculas e minúsculas, com aliases como "LAC" ou "EAP"):
  /api/v1/gefri?region=lac
• Ordenar resultados (o padrão é ordem decrescente para números):
  /api/v1/gefri?sort=score&order=asc
• Retornar apenas campos específicos de nível superior (correspondência sem diferenciar maiúsculas e minúsculas pelo nome real do campo):
  /api/v1/gefri?fields=Country Name,Country Code,Region
• Adicionar campos com alias (shortnames) sem remover os nomes longos:
  /api/v1/gefri?shortnames=true
• Selecionar um instantâneo histórico (dezembro de um determinado ano):
  /api/v1/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.

Notas de comportamento

• Se code ou codes for fornecido, o modo country tem prioridade mesmo quando level é omitido ou definido como global. level=country sem códigos de país é inválido.
• Tanto code quanto codes aceitam valores ISO3 separados por vírgulas. Quando ambos aparecem, codes tem prioridade.
• shortnames=true adiciona RegionShort e aliases curtos de componentes como score, access, innovation, human, governance e infra.
• O filtro de fields corresponde às chaves de nível superior sem diferenciar maiúsculas e minúsculas e mantém indicator_details quando esse array está presente.
• Todas as chaves de resposta que terminam com confidence são removidas recursivamente antes do retorno da carga útil.

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/v1/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• indicator_details aparece apenas em resultados em nível de país e é mantido mesmo quando o filtro fields é aplicado.

Ordenação

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

Estrutura de resposta e tratamento de erros

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

Tratamento de erros: Se uma solicitação for inválida, a resposta inclui uma chave error com uma mensagem descritiva. Por exemplo:
{ "apiVersion": "1", "error": "Invalid request." }

Quando exatamente um país corresponde, data é retornado como objeto. Quando vários países correspondem, data é retornado como array. Arquivos de países ausentes são ignorados, portanto códigos sem correspondência podem retornar count 0 em vez de 404.

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.