Coletor de CEPs Brasileiro

Este projeto é um script ETL (Extract, Transform, Load) que automatiza a coleta de municípios brasileiros através da API do IBGE e busca CEPs associados utilizando a API do ViaCEP, persistindo os dados em um banco de dados MongoDB.

🚀 Como Rodar o Projeto

A maneira mais simples de executar o projeto é utilizando o Docker Compose, que já configura tanto o banco de dados quanto a aplicação.

Pré-requisitos

• Docker instalado
• Docker Compose instalado

Passo a Passo

1. Subir os Containers: No diretório raiz do projeto, execute:

   docker compose up -d

   Isso irá:

   • Iniciar um container MongoDB.
   • Construir a imagem da aplicação Python.
   • Iniciar o processo de sincronização automaticamente.

2. Acompanhar os Logs: Para ver o progresso da coleta e sincronização:

   docker logs -f cep-app-1

3. Parar a Execução:

   docker compose down

🗄️ Conexão com o MongoDB

Dentro do Container (Docker)

A aplicação já está configurada para se conectar ao MongoDB dentro da rede do Docker utilizando a variável de ambiente MONGO_URI definida no docker-compose.yml:

• URI: mongodb://mongodb:27017/

Acesso Externo (Host)

Se você quiser conectar ao banco de dados usando uma ferramenta externa (como MongoDB Compass ou Robo 3T) enquanto os containers estão rodando:

• Hostname: localhost
• Porta: 27017
• URL de Conexão: mongodb://localhost:27017/

🔄 Como Funciona a Sincronização

O script main.py agora conta com maior resiliência e segue o seguinte fluxo:

1. Conexão Robusta: O script testa a conexão com o MongoDB via ping e utiliza um timeout de 5 segundos. Caso o banco não esteja acessível, ele encerra a execução com uma mensagem clara de erro.
2. Gerenciamento Automático de Índices: Na primeira execução, o script cria automaticamente índices únicos para ibge_id e cep, garantindo performance e evitando dados duplicados no banco.
3. Coleta de Municípios: Faz uma requisição para a API do IBGE para obter a lista de todos os municípios brasileiros (~5.571).
4. Persistência de Municípios: Salva os municípios no MongoDB (coleção municipios) de forma segura, verificando a estrutura de dados retornada (suporte a diferentes layouts de micro/mesorregião da API IBGE).
5. Busca de CEPs: Para cada município, faz uma consulta na API ViaCEP.
   • Atenção: Como o ViaCEP exige um logradouro, o script utiliza por padrão o termo "Rua" como exemplo pedagógico para buscar os registros.
6. Tratamento de Erros e Rate Limit:
   • Existe um delay obrigatório de 1.5 segundos entre cada chamada ao ViaCEP para evitar bloqueio de IP.
   • O script agora lida de forma isolada com erros em cada município (bloco try-except), permitindo que a coleta continue mesmo se um município específico falhar.
7. Idempotência: O script verifica se o município ou CEP já foi processado antes de fazer uma nova chamada, permitindo retomar a sincronização de onde parou em caso de interrupção.

⚠️ Observações Importantes

• Execução via Docker (Recomendada): Utilize o Docker Compose para rodar o projeto, pois ele garante que o MongoDB esteja configurado e acessível na rede interna do Docker. Execuções manuais via python3 main.py fora do container podem falhar se o MongoDB não estiver rodando no localhost:27017.
• Limites da API ViaCEP: A API retorna no máximo 50 registros por consulta.
• Bloqueio de IP: Não reduza o tempo de delay no main.py, pois o ViaCEP possui mecanismos rígidos contra data mining. Se receber um erro 429, o script aguardará automaticamente 60 segundos antes de tentar novamente.
• Banco de Dados: Os dados são persistidos em um volume Docker chamado mongo-data, garantindo que você não perca os dados ao reiniciar os containers.