Consulta CEP: por CEP ou por Endereço

Para fazer a consulta CEP nesta página, digite os 8 números do CEP no primeiro formulário, com ou sem hífen, e toque em “Consultar CEP”. O endereço aparece no cartão de resultado com logradouro, complemento, bairro, cidade, UF, código IBGE e DDD, quando a fonte informa esses dados. O que a fonte não devolve aparece como “—”.

A página consulta primeiro o ViaCEP. Se o ViaCEP não responder ou não encontrar o CEP, o navegador tenta a BrasilAPI, que devolve logradouro, bairro, cidade, UF e código IBGE, mas não traz complemento nem DDD. A fonte usada fica escrita no resultado, na linha “Fonte”, para você saber de onde veio cada informação.

Antes de qualquer consulta, a página confere se o CEP tem exatamente 8 números. Isso evita pedidos inválidos: quando o formato está errado, o ViaCEP responde com um erro sem os cabeçalhos que o navegador exige, e o navegador só mostraria uma falha sem explicação. Se o CEP não existir nas bases consultadas, a página avisa “CEP não encontrado.”. Para o caminho inverso, use o segundo formulário, abaixo do primeiro, que descobre o CEP a partir do estado, da cidade e da rua e mostra até 50 resultados.

Quando você sabe a rua mas não o CEP, use o segundo formulário. Escolha o estado na lista de UF, digite a cidade e a rua ou avenida, com 3 letras ou mais em cada um desses dois campos, e toque em “Buscar CEP”. A tabela de resultado mostra, para cada endereço encontrado, o CEP, o logradouro, o complemento, o bairro e a cidade com a UF, na ordem em que o serviço entregou.

A busca encontra o texto que você digitou dentro do nome da rua. Por isso, “Paulista” traz tanto a Avenida Paulista quanto ruas e vielas com esse nome, e a primeira linha pode ser uma viela, não a avenida que você procura. A ordem não é por relevância. Escrever o nome mais completo, como “Avenida Paulista”, reduz o número de linhas e coloca o endereço certo à vista.

Os acentos não atrapalham: “Sao Paulo” e “São Paulo” devolvem o mesmo conjunto de endereços, e “Rua dos Aimores” acha as mesmas ruas que “Rua dos Aimorés”. Cidade e rua com menos de 3 letras não são enviadas, e a página avisa o que corrigir. Nesta busca existe uma única fonte, o ViaCEP: a BrasilAPI não tem busca por endereço, então não há reserva caso o ViaCEP esteja fora do ar.

A consulta é feita pelo navegador de quem está usando a página, diretamente ao ViaCEP. Se o ViaCEP falhar ou não achar o CEP, o navegador tenta uma vez a BrasilAPI, e isso só vale para a consulta de CEP para endereço. O CEP ou o endereço digitado é enviado a esses serviços de terceiros, que recebem o pedido como qualquer visita ao site deles. O DarkBoxKit não guarda o que você digita e não envia nada a um servidor próprio.

A página também não faz varredura de CEPs nem monta uma base local: cada consulta acontece quando você toca no botão, uma por vez. É esse padrão de uso que as duas APIs pedem. O ViaCEP avisa que uso massivo para validar bases de dados locais pode levar ao bloqueio do acesso, e a BrasilAPI pede que o volume de consultas tenha a natureza de uma pessoa real consultando um dado.

Segundo a página do ViaCEP, os dados vêm de fontes como o IBGE, a GIA (só para São Paulo), a Anatel (DDD) e o SIAFI. Esta página apenas repassa o que o serviço devolve e não verifica a informação por conta própria. Também não há garantia de que ViaCEP e BrasilAPI estejam no ar quando você precisar.

As bases do ViaCEP e da BrasilAPI não são idênticas. O melhor exemplo é o CEP 99999999: o ViaCEP responde que não existe, mas a BrasilAPI devolve a Avenida das Torres, no Jardim Centro Cívico, em Sarandi, no Paraná. Por isso a página consulta a segunda fonte quando a primeira diz “erro”, e por isso o mesmo CEP pode aparecer em um serviço e faltar em outro.

CEPs novos ou de ruas recentes podem faltar em uma das bases, e esta página não promete atualização instantânea. Já o CEP 00000000 não existe em nenhuma das duas, e é com ele que a mensagem “CEP não encontrado.” aparece. Antes de concluir que o CEP não existe, confira se os 8 números foram digitados corretamente.

Há ainda a diferença entre “não encontrado” e “indisponível”. Se a rede falhar, o tempo de 8 segundos acabar ou os dois serviços responderem com erro, a página mostra “Não foi possível consultar agora. Tente de novo em instantes.”, porque esses serviços gratuitos não têm SLA nem garantia de disponibilidade. Nesse caso o CEP pode estar certo, e vale repetir a consulta depois de alguns instantes.

A busca por endereço tem limites que vêm do ViaCEP e que a página repete para você: mínimo de 3 letras na cidade e na rua, no máximo 50 resultados por consulta, nenhuma paginação e nenhuma ordenação por relevância. Quando a lista chega a exatamente 50 linhas, a página avisa “Mostrando os 50 primeiros resultados; informe mais letras da rua para refinar.”, porque pode haver mais endereços do que os exibidos.

Com muitos resultados, o caminho é refinar. Digite o nome da rua por inteiro, inclua o tipo (rua, avenida, travessa) quando souber e repita a busca. Num teste com “Rua” em Belo Horizonte, a lista chegou ao teto de 50 e cortou o resto. Em cidades grandes, nomes curtos e comuns quase sempre batem no limite, e a avenida certa pode ficar de fora da lista.

Se nenhum endereço for encontrado, a página mostra “Nenhum CEP encontrado para esse endereço.”. Confira então se o estado escolhido é o da cidade e se o nome da rua foi digitado por extenso; a busca só acha o que está na base do ViaCEP. Na busca por endereço, o complemento aparece quando o serviço o informa e ajuda a distinguir os resultados.

Quem desenvolve um cadastro ou um formulário de entrega pode usar o mesmo ViaCEP que esta página consulta. O trecho abaixo valida os 8 números antes de chamar, porque os erros 400 do ViaCEP chegam sem cabeçalho CORS, e trata como “não encontrado” a resposta de status 200 com {"erro":"true"}, que o ViaCEP usa para CEP inexistente. O código é executado nos testes do projeto com um fetch simulado, para o CEP 01001000 (Praça da Sé) e para o 00000000 (não encontrado).

async function consultarCep(cep) {
  const digitos = cep.replace(/[-\s]/g, "");
  if (!/^[0-9]{8}$/.test(digitos)) {
    throw new Error("Informe um CEP com 8 números.");
  }
  const resposta = await fetch("https://viacep.com.br/ws/" + digitos + "/json/");
  if (!resposta.ok) {
    throw new Error("Falha na consulta: " + resposta.status);
  }
  const dados = await resposta.json();
  if (dados.erro && dados.erro !== "false") {
    return null; // 200 com {"erro":"true"}: CEP não encontrado
  }
  return dados;
}

Os dois serviços são abertos, mas sem SLA e com pedido de uso moderado: faça a chamada a partir do navegador do usuário, uma por interação, e não use a API para varrer ou copiar a base de CEPs. Em fluxos de teste e cadastro, o gerador de CPF e CNPJ para testes fornece documentos fictícios, o validador de CPF confere o dígito verificador e o validador de placa Mercosul confere o formato da placa.

• ViaCEP: documentação da API
• BrasilAPI: documentação do CEP

Conteúdo informativo, sem caráter de consultoria jurídica, contábil ou financeira. Confirme sempre nas fontes oficiais.