Documentação · CEP

API pública de CEP

Sem chave

JSON aberto para consulta pontual de CEP. Sem chave, sem CAPTCHA, CORS em qualquer origem. Serve para um checkout, um cadastro ou um script pequeno — não para varrer o catálogo nem para postagem oficial.

20requisições por minuto, por IP

200requisições por dia, por IP

curl -s https://visioneagle.pro/api/public/cep/01310100

Uso consciente e limites

A cota é por endereço IP, em janela deslizante. As duas somam GET e HEAD dos três caminhos abaixo. OPTIONS (preflight CORS) não conta. As páginas HTML /cep/… também não.

Estouro responde HTTP 429 com Retry-After em segundos. Cacheie a resposta no seu lado e consulte de novo só se o endereço mudar. Volume maior: crie uma conta gratuita.

Consultar um CEP

GET https://visioneagle.pro/api/public/cep/{cep} — oito dígitos, com ou sem hífen. Também aceita HEAD.

curl -s https://visioneagle.pro/api/public/cep/01310100

Campos mais usados na resposta. A ficha ainda pode trazer logradouros e imoveis (omitidos no exemplo).

Campo	O que é
cep	CEP formatado, com hífen.
cep_numeros	Os 8 dígitos, sem pontuação — use este valor nas próximas URLs.
uf, municipio, bairro, logradouro	Endereço postal. Complemento descreve a faixa e o lado da rua, quando existir.
ibge, ddd	Código do município e DDD, quando a fonte postal tiver.
latitude, longitude	Coordenadas do Censo, quando houver imóvel georreferenciado.
fonte	Origem do bloco postal (Correios) ou do Censo (IBGE CNEFE 2022).
url, api	Ficha HTML e este mesmo JSON, já absolutos.

{
  "cep": "01310-100",
  "cep_numeros": "01310100",
  "uf": "SP",
  "municipio": "São Paulo",
  "bairro": "Bela Vista",
  "logradouro": "Avenida Paulista",
  "ibge": "3550308",
  "ddd": "11",
  "latitude": -23.5614,
  "longitude": -46.6565,
  "fonte": "Correios",
  "fonte_censo": "IBGE CNEFE 2022",
  "url": "https://visioneagle.pro/cep/01310100",
  "api": "https://visioneagle.pro/api/public/cep/01310100"
}

Buscar pelo endereço

GET https://visioneagle.pro/api/public/cep/busca — devolve uma lista de CEPs candidatos e, se o número bater, imóveis do Censo.

curl -s "https://visioneagle.pro/api/public/cep/busca?uf=SP&cidade=Sao%20Paulo&logradouro=Paulista&numero=1578"

Parâmetro	Obrigatório	Como preencher
uf	Sim	Dois caracteres. Ex.: SP, RJ, MG.
cidade	Quase sempre	Município. Aceita o alias localidade. Sem cidade, informe o número ou um logradouro com mais de uma palavra.
logradouro	Sim	Pelo menos 3 letras do nome da rua. Aceita o alias rua.
numero	Não	Número do imóvel. Afina a faixa (lado par/ímpar) e filtra casas do Censo.
cep	Não	Se vier com 8 dígitos, a busca vira a consulta direta do CEP.

A resposta traz ceps (lista), imoveis / imoveis_qtd e o numero usado na filtragem.

{
  "ceps": [
    {
      "cep": "01310-100",
      "cep_numeros": "01310100",
      "uf": "SP",
      "municipio": "São Paulo",
      "bairro": "Bela Vista",
      "logradouro": "Avenida Paulista"
    }
  ],
  "imoveis": [],
  "imoveis_qtd": 0,
  "numero": "1578",
  "fonte": "Correios"
}

Status do catálogo

GET https://visioneagle.pro/api/public/cep — sem path. Diz se a base está pronta. Entra na mesma cota.

curl -s https://visioneagle.pro/api/public/cep

Com o catálogo no ar, ready vem true junto de totais. Durante a carga, ready é false e as consultas de CEP/busca respondem 503.

Códigos, cabeçalhos e CORS

HTTP	Quando
200	Consulta ok. Corpo JSON em UTF-8.
204	OPTIONS de CORS. Sem corpo e sem gastar cota.
400	Busca sem UF e logradouro, UF inválida ou rua curta demais.
404	CEP com formato inválido ou ausente nesta base.
429	Cota do IP esgotada. Veja Retry-After.
503	Catálogo ainda em carga. O JSON traz mensagem com o progresso.

Cabeçalho	Função
X-RateLimit-Limit	Teto por minuto (20).
X-RateLimit-Remaining	Quanto ainda cabe nesta janela de um minuto.
X-RateLimit-Limit-Day	Teto por dia (200).
X-RateLimit-Remaining-Day	Quanto ainda cabe nas 24 horas.
Retry-After	Só no 429: segundos até tentar de novo.
Access-Control-Allow-Origin	Sempre *. Métodos GET, HEAD e OPTIONS.

Erro vem como {"detail": "…"}, salvo o 503 de carga, que replica o status do catálogo. Não faça laço em faixa de CEP, não espalhe a mesma origem em vários IPs para furar a cota, e não use esta API no lugar do DNE contratado dos Correios.

Fonte postal: catálogo dos Correios. Imóveis e código único: IBGE CNEFE, Censo Demográfico 2022. Esta API não substitui o DNE contratado para postagem oficial.