Documentação

Especificação completa: OpenAPI 3.1 (JSON). Crie sua chave em Minhas chaves.

Autenticação e limites

Envie a chave em Authorization: Bearer mun_… ou X-API-Key.
60 requisições por minuto por chave; veja X-RateLimit-Remaining e, ao exceder, 429 com Retry-After.
Erros seguem application/problem+json (RFC 9457), com mensagens em português.
Cada fonte informa origem: fonte, cache, cache_expirado, indisponivel ou sem_escopo.

Endpoints

GET /api/v1/municipios

Busca municípios de uma UF (paginado)

Escopo: `municipios`.

curl -s "https://api-municipios-agregadora.vercel.app/api/v1/municipios?uf=SP&nome=campinas&pagina=1&por_pagina=20" \
  -H "Authorization: Bearer $API_MUNICIPIOS_KEY"

GET /api/v1/municipios/{ibge}

Dados de um município

Escopo: `municipios`.

curl -s "https://api-municipios-agregadora.vercel.app/api/v1/municipios/3509502" \
  -H "Authorization: Bearer $API_MUNICIPIOS_KEY"

GET /api/v1/municipios/{ibge}/resumo

Resumo agregado: município + clima + feriados do período

Escopo: `municipios` (clima e feriados exigem os escopos `clima` e `feriados`; sem eles a fonte aparece como `sem_escopo`). Se uma fonte falhar, a resposta continua 200 com `parcial: true` e o erro da fonte em `meta.fontes`.

curl -s "https://api-municipios-agregadora.vercel.app/api/v1/municipios/3509502/resumo?de=2026-10-05&ate=2026-10-11" \
  -H "Authorization: Bearer $API_MUNICIPIOS_KEY"

GET /api/v1/feriados/{ano}

Feriados nacionais do ano

Escopo: `feriados`.

curl -s "https://api-municipios-agregadora.vercel.app/api/v1/feriados/2026" \
  -H "Authorization: Bearer $API_MUNICIPIOS_KEY"