Skip to content

README.md

Latest commit

 

History

History
68 lines (52 loc) · 3.91 KB

README.md

File metadata and controls

68 lines (52 loc) · 3.91 KB
Raw

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.