Documentação da API

Início rápido

A API é pública, sem cadastro e só de leitura. Cada página de dados do site tem um gêmeo na API, no mesmo caminho, com /api/v1 no lugar de /dados. Os números são sempre agregados por lugar (país, região, estado ou município), nunca por escola.

# Indicadores de Curitiba em JSON
curl https://honeycomb.app.br/api/v1/panorama-ei/municipio/pr/curitiba

# O mesmo em CSV
curl "https://honeycomb.app.br/api/v1/panorama-ei/municipio/pr/curitiba?formato=csv"

# Achar o endereço de um lugar pelo nome
curl https://honeycomb.app.br/api/v1/panorama-ei/geografias

Endereços

Hoje há um conjunto de dados, o Panorama da Educação Infantil no Brasil 2026, em /api/v1/panorama-ei. A raiz /api/v1 lista os conjuntos disponíveis.

O nome do município vai em minúsculas, sem acento, com hífens no lugar de espaços e sem apóstrofo (São José dos Pinhais → sao-jose-dos-pinhais). A UF entra no caminho porque há nomes repetidos entre estados. Se o IBGE renomear um município, o endereço novo passa a valer e o antigo redireciona; o id (mun-4106902) nunca muda. Para não montar caminhos à mão, use url_api de /geografias.

Nesta versão há página para o Brasil, as regiões, os estados e 397 municípios (os que têm 10 ou mais escolas privadas puras, e todas as capitais). Os demais aparecem em /geografias, sem url_api, e respondem 404.

JSON e CSV

A resposta padrão é JSON. Para CSV, acrescente ?formato=csv ou envie o cabeçalho Accept: text/csv. O CSV vem em UTF-8, separado por vírgula, com ponto decimal e uma linha por indicador e ano:

geografia_id,indicador,ano,valor,unidade,suprimido,fonte
mun-4106902,escolas_ei_pura,2025,241,escolas,,"INEP, Censo Escolar 2025 (microdados)"

Campos da resposta

Valores numéricos vêm sempre como número, nunca como texto formatado, e percentuais vão de 0 a 100. Cada célula traz id, ano, valor, unidade e fonte:

{
  "id": "escolas_ei_pura",
  "ano": 2025,
  "valor": 241,
  "unidade": "escolas",
  "fonte": "INEP, Censo Escolar 2025 (microdados)",
  "comparacao": {
    "ano": 2020,
    "valor": 286,
    "variacao_pct": -15.7
  }
}

Valores não divulgados

Para não expor os números de uma escola específica, todo valor que descreveria menos de 3 escolas privadas sai como null, com o motivo no campo suprimido:

{
  "id": "mat_ei_conveniada",
  "ano": 2025,
  "valor": null,
  "unidade": "matrículas",
  "fonte": "INEP, Censo Escolar 2025 (microdados)",
  "suprimido": "menos_de_3_escolas"
}

• null não é zero. Um zero de verdade (nenhuma escola conveniada no lugar, por exemplo) sai como 0.
• Nas séries, um ponto [ano, null] é um ano não divulgado. Na comparacao, variacao_pct é null se um dos dois anos não é divulgado.
• Por causa da supressão, a soma dos municípios publicados pode não fechar com o total do estado. Isso é esperado: a diferença inclui os municípios sem página e os valores ocultos.
• O número de escolas (escolas_ei_pura, escolas_ei_conveniada) é sempre publicado, porque não revela dados de nenhuma escola.

Indicadores sujeitos a essa regra têm sigilo: true em /api/v1/panorama-ei/indicadores.

Indicadores

Lista desta versão. Definições completas, anos e níveis em /api/v1/panorama-ei/indicadores.

Como citar

Os dados derivados estão sob licença CC-BY-4.0: use à vontade, inclusive comercialmente, citando a fonte. Cada resposta traz o texto pronto em citacao:

Honeycomb / OSLO., Panorama da Educação Infantil no Brasil 2026, dados de Curitiba (PR). Disponível em https://honeycomb.app.br/dados/panorama-ei/municipio/pr/curitiba. Acesso em <data>.

Ao citar um número, prefira linkar a url_canonica (exemplo). As fontes primárias são o INEP (Censo Escolar) e o IBGE, ambas de dados abertos.

Versões e uso

Os dados são atualizados uma vez por ano, com o Censo Escolar. A versão atual é 2026.10.2, gerada em 2026-10-29. Cada versão entra em /api/v1/panorama-ei/changelog, com descrição e o SHA-256 dos arquivos em lote. Os id de lugares e de indicadores não mudam entre versões; os valores, sim.

Não é preciso cadastro nem chave. Como os dados mudam pouco, guarde as respostas em cache em vez de consultar a mesma URL repetidamente. Use só GET.

Respostas de erro