Brasil CEP para Endereco - Apify Actor

Actor da Apify que recebe um ou varios CEPs brasileiros e devolve enderecos estruturados. A consulta usa o endpoint CEP v2 da BrasilAPI, projeto open source mantido em github.com/BrasilAPI/BrasilAPI.

Entrada

{
  "ceps": ["01001-000", "30130-010"],
  "maxConcurrency": 5,
  "timeoutSecs": 10,
  "maxRetries": 2,
  "failOnError": false
}

• ceps: de 1 a 1.000 CEPs, com ou sem pontuacao.
• maxConcurrency: consultas simultaneas, entre 1 e 20.
• timeoutSecs: tempo limite de cada tentativa.
• maxRetries: repeticoes para erros temporarios (HTTP 429/5xx ou rede).
• failOnError: faz a execucao falhar caso algum CEP nao seja resolvido; os resultados ainda sao salvos.

Saida

Cada CEP gera um item no dataset:

{
  "inputCep": "01001-000",
  "success": true,
  "cep": "01001-000",
  "street": "Praca da Se",
  "neighborhood": "Se",
  "city": "Sao Paulo",
  "state": "SP",
  "fullAddress": "Praca da Se, Se, Sao Paulo - SP, CEP 01001-000, Brasil",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "service": "open-cep",
  "error": null
}

O registro OUTPUT do key-value store contem um resumo com total, succeeded, failed e finishedAt.

Executar localmente

Requisitos: Node.js 22 ou superior.

npm install
npm test
npm start

A entrada local fica em storage/key_value_stores/default/INPUT.json.

Publicar a partir do GitHub

1. Crie um repositorio no GitHub e envie estes arquivos.
2. Na Apify Console, crie um Actor e escolha Git repository como origem.
3. Informe a URL do repositorio e use Dockerfile como arquivo de build.
4. Execute o build e teste com um CEP conhecido.

Tambem e possivel instalar a Apify CLI e publicar diretamente com apify push.

Observacoes

• CEPs invalidos ou nao encontrados geram itens com success: false; o lote continua.
• A disponibilidade e a cobertura dos dados dependem da BrasilAPI e de seus provedores.
• O Actor nao exige token da BrasilAPI.