API de consulta de CEPs brasileiros com cache local e fallback automático para ViaCEP. Compatível 100% com a API do ViaCEP.

• Cache Local: Base de dados completa de CEPs brasileiros servida localmente para máxima performance
• Fallback Inteligente: Quando o CEP não está na base local, faz proxy automático para o ViaCEP
• Pesquisa por Endereço: Suporta pesquisa por UF/Cidade/Logradouro (proxy para ViaCEP)
• 100% Compatível: Mesma API e formato de resposta do ViaCEP
• Containerizado: Deploy fácil com Docker/Podman
• Leve e Rápido: Nginx Alpine com base de dados estática

• Docker ou Podman
• Docker Compose

1. Clone o repositório:

git clone https://github.com/ricardoapaes/opencep.git
cd opencep

2. Configure o ambiente (opcional):

# Copiar arquivo de exemplo
cp .env.example .env

# Editar se necessário
# OPENCEP_VERSION=2.0.1
# DOCKER_BUILDKIT=1  # Habilita cache otimizado

3. Inicie o container:

# Opção 1: Usando o script helper (recomendado)
./build.sh
docker compose up -d

# Opção 2: Manual com BuildKit habilitado
export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

docker compose up -d --build

A API estará disponível em http://localhost:8080

Endpoint: /ws/{cep}/{formato}/

Parâmetros:

• cep: CEP com 8 dígitos (apenas números)
• formato: json ou xml

Exemplos:

# CEP de São Paulo
curl http://localhost:8080/ws/01001000/json/

# CEP do Rio Grande do Sul
curl http://localhost:8080/ws/87308084/json/

Resposta:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
}

Endpoint: /ws/{UF}/{Cidade}/{Logradouro}/{formato}/

Parâmetros:

• UF: Sigla do estado (2 letras maiúsculas)
• Cidade: Nome da cidade (mínimo 3 caracteres)
• Logradouro: Nome do logradouro (mínimo 3 caracteres)
• formato: json ou xml

Exemplos:

# Pesquisar por "Domingos" em Porto Alegre/RS
curl http://localhost:8080/ws/RS/Porto%20Alegre/Domingos/json/

# Pesquisar por "Domingos Jose" em Porto Alegre/RS
curl http://localhost:8080/ws/RS/Porto%20Alegre/Domingos%20Jose/json/

# Pesquisar por "Paulista" em São Paulo/SP
curl http://localhost:8080/ws/SP/São%20Paulo/Paulista/json/

Resposta (retorna até 50 CEPs):

[
  {
    "cep": "90420-010",
    "logradouro": "Rua Domingos José Poli",
    "complemento": "",
    "bairro": "Auxiliadora",
    "localidade": "Porto Alegre",
    "uf": "RS",
    "ibge": "4314902",
    "gia": "",
    "ddd": "51",
    "siafi": "8801"
  }
]

Endpoint: /v1/{cep}.json

Acessa diretamente a base de dados local sem fallback.

curl http://localhost:8080/v1/01001000.json

Endpoint: /health

Verifica se o serviço está funcionando.

curl http://localhost:8080/health

Resposta:

{
  "status": "ok",
  "service": "opencep-api",
  "timestamp": "2025-10-16T10:30:45-03:00"
}

┌─────────────┐
│   Cliente   │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────┐
│          Nginx (Alpine)              │
│  ┌────────────────────────────────┐ │
│  │  /ws/{cep}/{formato}/          │ │
│  │  1. Try local: /v1/{cep}.json  │ │
│  │  2. Fallback: ViaCEP           │ │
│  └────────────────────────────────┘ │
│  ┌────────────────────────────────┐ │
│  │  /ws/{UF}/{Cidade}/{Log...}/   │ │
│  │  Proxy: ViaCEP                 │ │
│  └────────────────────────────────┘ │
└─────────────────────────────────────┘
       │                    │
       ▼                    ▼
┌──────────────┐    ┌──────────────┐
│ Base Local   │    │   ViaCEP     │
│ (JSON files) │    │   (Proxy)    │
└──────────────┘    └──────────────┘

• OPENCEP_VERSION: Versão da base de dados OpenCEP (padrão: 2.0.1)

• 8080: Porta HTTP exposta (configurável no docker-compose.yml)

Edite o docker-compose.yml para alterar configurações:

services:
  opencep-api:
    build:
      args:
        - OPENCEP_VERSION=2.0.1  # Alterar versão da base
    ports:
      - "8080:80"  # Alterar porta externa

Visualizar logs em tempo real:

docker compose logs -f

Ver últimas 200 linhas:

docker compose logs -f --tail=200

opencep/
├── Dockerfile           # Multi-stage build: download base + nginx
├── docker-compose.yml   # Orquestração do container
├── nginx.conf          # Configuração das rotas e proxy
├── build.sh            # Script helper para builds otimizados
├── .env.example        # Exemplo de variáveis de ambiente
└── README.md           # Este arquivo

docker compose down
docker compose build --no-cache
docker compose up -d

O projeto usa BuildKit cache mounts para evitar downloads repetidos da base de dados:

Performance:

• 🐌 Primeiro build: Download completo (~500MB) - ~2-3 minutos
• 🚀 Builds subsequentes: Usa arquivo em cache - ~10-20 segundos!
• 💾 Cache persistente: Arquivos mantidos entre builds

Como funciona:

Primeiro build:  Download 500MB → Extrai → Build imagem
                 ⏱️  ~2-3 minutos

Segundo build:   Cache hit! → Extrai → Build imagem
                 ⏱️  ~10-20 segundos (15x mais rápido!)

Para habilitar o BuildKit (recomendado):

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
docker compose build

Ou use o script helper:

./build.sh

# Testar CEP local
curl -i http://localhost:8080/ws/01001000/json/

# Testar fallback (CEP inexistente na base local)
curl -i http://localhost:8080/ws/99999999/json/

# Testar pesquisa por endereço
curl -i http://localhost:8080/ws/RS/Porto%20Alegre/Domingos/json/

Este projeto utiliza a base de dados do OpenCEP, que é baixada automaticamente durante o build da imagem.

Versões disponíveis: Veja as releases do OpenCEP

• Base de Dados: OpenCEP por SeuAliado
• API de Fallback: ViaCEP

Este projeto é fornecido "como está", sem garantias. Use por sua conta e risco.

• A pesquisa por endereço sempre usa o ViaCEP (não há base local para essa funcionalidade)
• CEPs novos não presentes na base local serão consultados via ViaCEP

• Atualização automática da base de dados
• Suporte a HTTPS
• Métricas e monitoramento
• Cache de respostas do ViaCEP
• Health check endpoint

Para dúvidas ou sugestões, abra uma issue.

Desenvolvido com ❤️ usando Nginx + OpenCEP + ViaCEP