API de CEP: como consultar CEP via API (ViaCEP e BrasilAPI)

O que é uma API de CEP

Uma API de CEP é um serviço público que transforma um CEP em endereço, ou um endereço em CEP, por meio de uma requisição na internet. A resposta costuma vir em JSON.

Quando se fala em api de cep, fala-se de uma ponte entre o seu formulário e uma base de endereços. Em vez de manter milhões de registros, você consulta o serviço e usa só o resultado.

Como a consulta funciona

O navegador ou o servidor envia o CEP, a API procura na base e devolve os campos do endereço.

Quem usa uma API de CEP

• Lojas virtuais e marketplaces.
• Aplicativos de entrega.
• Sistemas de cadastro de clientes.
• Páginas de contato e de agendamento.

Código postal é CEP?

Sim: CEP é o código postal do Brasil, a sigla de Código de Endereçamento Postal. Em outros países o mesmo conceito aparece com nomes diferentes, como ZIP code nos Estados Unidos.

O CEP brasileiro tem 8 dígitos no padrão NNNNN-NNN, foi criado pelos Correios em 1971 e passou a ter 8 dígitos em 1992. Saiba mais em o que é CEP.

Código postal e CEP são a mesma coisa

Na prática, sim. "Código postal" é o termo geral; CEP é o nome brasileiro.

Diferença entre CEP e outros códigos

Cada país tem formato próprio. O brasileiro tem 8 dígitos; o americano, 5 ou 9; o português, 7.

O que é CEP código postal na API

Na API, o código postal vem no campo "cep" da resposta, no formato com hífen. Os demais campos descrevem o endereço.

Quem pesquisa "o que é cep código postal" encontra a explicação no contexto de formulários: o campo é a chave da consulta, e o resultado preenche o resto. A estrutura do CEP explica o que cada parte do número significa.

Campos mais comuns

• cep: o número consultado.
• logradouro: nome da rua.
• bairro: bairro ou distrito.
• localidade: cidade.
• uf: sigla do estado.

Campos adicionais

O ViaCEP também devolve ibge e ddd, úteis para integrações.

ViaCEP: como funciona

O ViaCEP é um webservice gratuito e público que devolve o endereço de um CEP em JSON, XML e outros formatos. A consulta é feita por uma URL simples.

O modelo da requisição é `https://viacep.com.br/ws/CEP/json/`, trocando CEP pelos 8 dígitos sem hífen. O viacep não exige cadastro nem chave, o que facilita o início do projeto.

Formatos de resposta. O mais usado é JSON. O serviço também oferece outras saídas para sistemas antigos.

Cuidados com o ViaCEP. Serviços gratuitos podem ter instabilidade e limites de uso. Planeje uma alternativa de reserva.

BrasilAPI CEP: como funciona

O BrasilAPI reúne vários serviços públicos brasileiros, e a rota de CEP devolve o endereço a partir do número. É uma ótima alternativa ao ViaCEP.

A consulta com brasilapi cep segue o modelo `https://brasilapi.com.br/api/cep/v1/CEP`. Existem versões da rota, e a mais nova costuma trazer dados extras, como coordenadas em alguns casos.

Quando usar o BrasilAPI

Como reserva do ViaCEP ou como fonte principal, se a sua equipe já usa outros serviços do projeto.

Diferenças de resposta

Os nomes dos campos podem mudar, então trate a resposta de cada API separadamente.

API CEP grátis: vale a pena

Sim, as APIs gratuitas atendem a maioria dos sites, mas é preciso prever falhas e limites de uso. Para grandes volumes, avalie serviços pagos.

A busca por api cep gratis costuma terminar em ViaCEP e BrasilAPI, que cobrem o uso comum. Em projetos críticos, combine duas fontes, com uma delas de reserva, e guarde em cache os resultados já consultados.

Vantagens

• Sem custo de entrada.
• Sem chave de acesso.
• Documentação simples.

Limitações

• Sem garantia formal de disponibilidade.
• CEPs novos podem demorar a aparecer.
• Limites de uso podem existir.

Consulta CEP API: passo a passo

Para fazer uma consulta de CEP por API, limpe o número, envie a requisição e trate a resposta ou o erro. São quatro etapas simples.

1. Remova hífen e espaços do CEP digitado.
2. Verifique se restaram 8 dígitos.
3. Envie a requisição à API.
4. Leia o JSON e preencha os campos, ou mostre mensagem de erro.

Exemplo de URL

Para o CEP 01001-000, a URL do ViaCEP seria `https://viacep.com.br/ws/01001000/json/`.

Exemplo de resposta

A resposta traz logradouro, bairro, localidade e uf. Para o exemplo acima, o endereço é a Praça da Sé, em São Paulo.

Webservice CEP: o que mudou com as APIs

O webservice de CEP, antes baseado em SOAP e XML, hoje costuma ser uma API REST em JSON, mais leve e fácil de usar. O conceito é o mesmo.

Quem trabalha com sistemas legados ainda encontra o webservice cep em XML. Para projetos novos, prefira JSON e chamadas REST, que funcionam bem em qualquer linguagem.

SOAP versus REST

SOAP é mais verboso. REST usa URLs simples e retorna dados enxutos.

Migrando de sistemas antigos

Mantenha a camada de consulta isolada. Trocar a fonte depois fica muito mais fácil.

CEP JSON: formato da resposta

O CEP em JSON é um objeto com campos de texto, como cep, logradouro, bairro, localidade e uf. É fácil de ler em qualquer linguagem.

Ao pedir cep json ao ViaCEP, você recebe um objeto simples. Se o CEP não existir, a resposta traz um campo de erro, que o código deve tratar para não quebrar o formulário.

Resposta de sucesso. Contém os dados do endereço, com acentuação em UTF-8.

Resposta de erro. No ViaCEP, o CEP inexistente retorna um objeto com o campo "erro". Já um CEP com formato errado pode devolver erro de requisição.

Consultar CEP em JavaScript

Em JavaScript, use fetch para chamar a API, converter a resposta em JSON e preencher os campos do formulário. Poucas linhas bastam.

Quem precisa consultar cep javascript deve limpar o número, validar que tem 8 dígitos e chamar a URL. Depois, trate o erro e mostre uma mensagem clara ao usuário quando o CEP não for encontrado.

Passos da implementação

1. Capture o evento de saída do campo CEP.
2. Remova caracteres não numéricos.
3. Chame a API com fetch.
4. Preencha rua, bairro, cidade e estado.

Tratamento de falhas

Use try e catch. Se o ViaCEP falhar, tente o BrasilAPI antes de pedir preenchimento manual.

Autocomplete CEP no formulário

O autocomplete de CEP preenche rua, bairro, cidade e estado assim que o usuário termina de digitar os 8 números. O cliente só informa número e complemento.

O autocomplete cep melhora a experiência no celular e reduz erros. Um bom desenho de formulário deixa os campos editáveis, para que o usuário corrija se a base estiver defasada.

Boas práticas de usabilidade

• Teclado numérico no campo CEP.
• Máscara com hífen automático.
• Indicador de carregamento curto.
• Campos editáveis depois do preenchimento.

Quando desativar o preenchimento

Em CEP geral de localidade, rua pode vir vazia. Deixe o campo livre para digitação.

Validar o CEP antes de consultar a API

Valide o formato antes de chamar a API para economizar requisições e evitar erros de resposta. Uma expressão regular simples resolve.

Basta aceitar 8 dígitos, com hífen opcional. Para existência, a consulta real é necessária. Veja a validação de CEP para entender os dois níveis de checagem.

Formato. Oito algarismos, no padrão NNNNN-NNN.

Existência. Só a API ou o DNE confirmam se o número está em uso.

Consultar endereço para achar o CEP pela API

Você também pode pesquisar o CEP a partir do endereço, informando UF, cidade e parte do nome da rua. O ViaCEP oferece essa consulta.

O modelo é `https://viacep.com.br/ws/UF/Cidade/Logradouro/json/`. O resultado é uma lista de possíveis CEPs, que o usuário escolhe. Para a mesma função na interface, veja a busca por endereço.

Quando usar

Quando o cliente não sabe o CEP, mas sabe a rua e a cidade.

Cuidados

Nomes de rua repetidos em uma cidade devolvem várias opções. Peça o bairro para filtrar.

Qual o CEP de São Paulo capital

A capital paulista não tem um único CEP, pois cada rua tem o seu número. O CEP de São Paulo fica na faixa de 01000-000 a 19999-999, que é a do estado.

Para o cep de são paulo capital, informe a rua e o bairro. Um exemplo real: a Avenida Brasil, no bairro Cidade Luz, tem o CEP 04877-210. A página de São Paulo reúne orientações sobre ruas e bairros.

CEP São Paulo capital e CEP SP capital

As buscas por cep sao paulo capital e por cep sp capital têm a mesma resposta: depende da rua.

CEP de referência

O CEP 01001-000 é o da Praça da Sé, ponto bem conhecido do centro.

Qual o CEP de Capitão Poço

Capitão Poço, no Pará, usa o CEP geral 68650-000 nos dados consultados. Em municípios menores, é comum haver um único CEP para a cidade.

Quem pergunta o cep de capitão poço ou cep capitão poço deve usar esse número como ponto de partida e confirmar nos Correios se precisar de comprovação. Veja a página de Capitão Poço.

Como a API responde

Para um CEP geral, rua e bairro podem vir vazios, e a cidade e a UF vêm preenchidas.

Formulário flexível

Deixe o campo de rua editável para quem mora em cidade de CEP único.

CEP de Arapiraca e CEP Arapiraca centro

Arapiraca é uma cidade de Alagoas, e o CEP depende da rua ou do bairro consultado. Para o centro, informe o logradouro.

Quem pesquisa cep arapiraca ou cep de arapiraca deve usar a busca por endereço. O cep arapiraca centro varia conforme a rua do centro. Confira a faixa de CEP de Alagoas.

Como achar a rua

Informe UF, cidade e nome da rua, e a API devolve as opções.

Conferir o resultado

Compare bairro e logradouro com o endereço de uma conta recente.

CEP de Itapipoca e CEP Itapipoca

Itapipoca fica no Ceará, e o CEP de cada endereço depende da rua. Use a busca para obter o número certo.

Para o cep itapipoca ou o cep de itapipoca, a consulta por endereço é o caminho mais seguro. O estado usa a faixa de 60000-000 a 63999-999, detalhada em CEP do Ceará.

Qual o CEP de Itapipoca

Não existe um único número se a cidade tiver várias ruas cadastradas. Pesquise pelo logradouro.

Integração com API

O mesmo código de consulta serve para Itapipoca e para qualquer outra cidade.

CEP de Capim Grosso e CEP Capim Grosso

Capim Grosso é um município da Bahia, e o CEP é obtido pela busca por rua ou por localidade. Em cidades pequenas, o CEP geral pode bastar.

O cep capim grosso e o cep de capim grosso devem ser pesquisados na ferramenta. Veja a faixa em CEP da Bahia. Se a busca devolver um único número, é provável que seja o CEP geral.

Qual o CEP de Capim Grosso

Pesquise o nome da cidade e leia o resultado. Em caso de dúvida, confirme com os Correios.

Dados de apoio

A API devolve também o DDD e o código IBGE, úteis para cadastros.

CEP de Santa Cruz do Capibaribe

Santa Cruz do Capibaribe fica em Pernambuco, e o CEP é definido por rua. A busca por endereço devolve o número certo.

Quem procura cep santa cruz do capibaribe ou cep de santa cruz do capibaribe pode usar a ferramenta de busca ou a API. Veja o CEP de Pernambuco para entender a faixa estadual.

Como pesquisar

Digite o nome da rua e escolha a cidade na lista de resultados.

Verificação

Valide o CEP encontrado na validação para conferir a cidade e o estado.

CEP Capinzal e CEP de Capinzal

Capinzal é uma cidade de Santa Catarina, e o CEP varia conforme a rua. Consulte pelo endereço.

O cep capinzal e o cep de capinzal são pesquisas comuns de quem precisa preencher cadastros. A faixa do estado está em CEP de Santa Catarina.

Cidades de nomes parecidos. Capinzal, Capivari de Baixo e Capim Grosso são nomes distintos. Confirme a UF antes de usar o CEP.

CEP Capivari de Baixo

O cep capivari de baixo também é de Santa Catarina e segue a mesma lógica de busca por rua.

CEP de Itapicuru, CEP Itapira e CEP Itapipoca

Itapicuru, Itapira e Itapipoca têm nomes parecidos, mas ficam em estados diferentes, então confira sempre a UF. O CEP depende da cidade e da rua.

Ao pesquisar o cep itapicuru ou o cep de itapicuru, selecione a UF correta. O cep itapira costuma ser de cidade de São Paulo. A diferença evita erros de entrega.

Por que a UF importa

Nomes iguais ou parecidos existem em vários estados e geram confusão em formulários.

Como a API ajuda

Ao informar UF e cidade, a consulta por endereço filtra os resultados.

CEP Carapicuíba, Tapiratiba e Sapiranga

Carapicuíba e Tapiratiba ficam em São Paulo; Sapiranga fica no Rio Grande do Sul. Cada uma tem CEPs por rua.

Quem pergunta "qual é o CEP de Carapicuíba" deve usar a busca por endereço. O cep carapicuiba, o cep tapiratiba e o cep sapiranga são consultados da mesma forma. Veja CEP de São Paulo e CEP do Rio Grande do Sul.

Cidade grande e cidade pequena

Em cidades maiores, o CEP é por rua. Em menores, pode ser geral.

Usar a mesma API

Qualquer uma dessas cidades é consultada pelo mesmo endpoint.

CEP de Capistrano, Ibiapina e Capitão Enéas

Capistrano e Ibiapina ficam no Ceará, e Capitão Enéas em Minas Gerais. O CEP de cada endereço segue a regra do município.

Pesquise o cep de capistrano, o cep ibiapina e o cep capitão enéas pela ferramenta. As faixas do Ceará e de Minas Gerais ajudam a conferir se o número retornado pertence ao estado.

Conferir pelo primeiro dígito

CEPs de Minas Gerais começam com 3. Os do Ceará começam com 6.

Resultado inesperado

Se o estado não bate, revise a digitação ou o nome da cidade.

CEP de Inhangapi e de Apicum-Açu

Inhangapi fica no Pará e Apicum-Açu no Maranhão. Em municípios pequenos, é comum haver um único CEP geral.

O cep de inhangapi e o cep de apicum-açu devem ser pesquisados pelo nome da cidade. Veja CEP do Pará e CEP do Maranhão para a faixa de cada estado.

Qual o CEP de Inhangapi

Pesquise o município e veja se a resposta traz um número único ou vários.

CEP em municípios pequenos

Quando só há um CEP, ele serve para toda a cidade, mesmo para endereços rurais.

CEP da Aldeia Jaguapiru e localidades especiais

Aldeias, comunidades e distritos podem ter CEP próprio ou usar o da sede do município. A consulta pela API mostra o que está cadastrado.

Quem busca o cep da aldeia jaguapiru precisa pesquisar pelo nome da localidade e pelo município. Em localidades especiais, a resposta pode trazer apenas a cidade, e o endereço é complementado à mão.

Como tratar no formulário

Permita o preenchimento manual da rua e do complemento.

Confirmação oficial

Para endereços pouco comuns, consulte os Correios para confirmar o CEP correto.

Como escolher entre ViaCEP e BrasilAPI

Para a maioria dos projetos, use o ViaCEP como principal e o BrasilAPI como reserva, ou o inverso. O importante é ter as duas.

Compare estabilidade, formato de resposta e documentação. O CEP BR adota essa combinação, descrita em metodologia e fontes.

• ViaCEP: consulta por CEP e por endereço.
• BrasilAPI: várias rotas e versões.
• Reserva: tente a segunda API se a primeira falhar.
• Cache: guarde resultados para economizar chamadas.

Critérios de escolha

Disponibilidade, formato dos dados e facilidade de uso pesam mais que qualquer detalhe técnico.

Combinar as duas

Uma função que tenta a primeira e, em falha, a segunda, aumenta muito a confiabilidade.

Cache e desempenho nas consultas de CEP

Guardar em cache os CEPs já consultados reduz chamadas, acelera o formulário e diminui o risco de atingir limites. O endereço de um CEP raramente muda.

Um cache simples por CEP já ajuda, e o tempo de validade pode ser de dias. Em sistemas com muitos acessos, isso economiza recursos e melhora a experiência do cliente.

Onde guardar

Em memória, no navegador ou em banco de dados, conforme o projeto.

Quando renovar

Atualize periodicamente, pois CEPs podem ser alterados ou criados.

Erros comuns ao integrar uma API de CEP

Os erros mais comuns são enviar o CEP com hífen sem tratar, não lidar com respostas de erro e não prever indisponibilidade. Todos são fáceis de evitar.

• Não limpar o CEP antes da consulta.
• Ignorar o campo de erro da resposta.
• Bloquear o formulário se a API falhar.
• Salvar o CEP como número e perder o zero inicial.
• Não testar com CEPs que começam com zero.

O problema do zero à esquerda

CEPs de São Paulo começam com 0. Armazene como texto.

Falha de rede

Sem internet ou com API fora do ar, permita preenchimento manual.

Segurança e privacidade em consultas de CEP

A consulta a uma API pública envia o CEP a um servidor externo, então não envie dados pessoais junto. O CEP sozinho não identifica ninguém.

No CEP BR, as consultas partem do navegador do usuário e nada é armazenado. Em sistemas próprios, evite registrar o CEP junto a nome e documento sem necessidade, em respeito à LGPD.

Boas práticas

• Use HTTPS sempre.
• Não registre dados desnecessários.
• Informe o usuário sobre o uso do CEP.

Localização do usuário

Se usar a localização, peça permissão e use o dado apenas para achar o CEP, como na ferramenta de CEP da minha localização.

Limites e precisão das APIs de CEP

Nenhuma API é 100% precisa: ruas novas podem demorar a aparecer e alguns CEPs podem mudar. Para comprovação oficial, consulte os Correios.

As APIs públicas dependem de atualizações de terceiros a partir do DNE. Planeje mensagens que permitam correção manual e confirmação do endereço pelo cliente.

• CEPs recentes podem faltar.
• Há limite de requisições.
• Serviços podem sair do ar.

Como lidar com defasagem

Permita edição dos campos e registre falhas para análise.

Fonte oficial

Para o dado de referência, veja o CEP Correios.

API de CEP em PHP, Python e outras linguagens

Qualquer linguagem que faça requisições HTTP consome uma API de CEP: PHP, Python, Java, C#, Node.js e outras. O modelo é sempre o mesmo.

O fluxo é: montar a URL, enviar a requisição, ler o JSON e tratar o erro. Os nomes das bibliotecas mudam, mas a lógica é igual em todas as linguagens.

Bibliotecas HTTP

Use a biblioteca padrão da linguagem ou uma de sua preferência.

Tempo limite

Defina um timeout curto. Isso evita travar o formulário quando a API demora.

Testar a integração com CEPs de exemplo

Teste a integração com um CEP real conhecido, um CEP inexistente e um CEP malformado. Os três cenários cobrem os casos essenciais.

Use 01001-000 como exemplo real. Para testar o erro, o gerador de CEP cria números fictícios que provavelmente não existem. Valide também no navegador, para ver o comportamento do formulário.

• CEP real: preenche os campos.
• CEP inexistente: mostra mensagem.
• CEP malformado: bloqueia antes da consulta.

Casos de borda

Teste CEPs que começam com zero e CEPs gerais de cidades pequenas.

Testes automatizados

Simule respostas da API em vez de chamar o serviço real em todos os testes.

Como escolher uma API CEP para o seu projeto

Escolha a API CEP pela estabilidade, pela clareza da documentação e pela facilidade de ter uma segunda fonte de reserva. Preço importa menos quando as opções gratuitas já atendem.

Antes de decidir, liste o que o seu sistema precisa: apenas consulta por número, ou também por endereço? Há muito volume de acessos ou só alguns cadastros por dia? As respostas mudam a escolha e o desenho do cache.

• Consulta só por CEP: qualquer API gratuita resolve.
• Consulta por endereço: confirme que o serviço oferece a rota.
• Alto volume: use cache e considere serviço pago.
• Projeto crítico: combine duas fontes diferentes.

Uma API CEP bem escolhida torna o cadastro mais rápido e reduz os pedidos devolvidos. Revise a escolha de tempos em tempos, pois serviços públicos podem mudar regras de uso sem aviso.

Arquitetura de uma consulta com API CEP

Em uma arquitetura simples, o navegador chama a API CEP diretamente; em outra, o servidor faz a chamada e entrega o resultado ao navegador. Cada uma tem vantagens.

Chamar do navegador é rápido de implementar e não consome o servidor, que é o modelo usado pelo CEP BR. Chamar do servidor permite cache central, registro de falhas e troca de fonte sem alterar o site, o que ajuda em sistemas maiores.

• Navegador: simples, sem custo de servidor.
• Servidor: cache central e controle de limite.
• Híbrido: servidor com reserva e navegador como segunda tentativa.

Seja qual for o modelo, a lógica de limpar o número, validar o formato e tratar erros fica igual. Veja a validação de CEP para testar números antes de integrar, e a busca de CEP para ver o resultado final na interface.

Pense também em como o seu sistema se comporta quando a API demora. Um indicador de carregamento curto e um limite de tempo evitam que o usuário fique esperando sem saber o que acontece. Depois do limite, ofereça preenchimento manual e registre a falha para análise posterior.

Por fim, documente internamente qual API é a principal, qual é a reserva e como trocar entre elas. Essa documentação simples economiza horas quando um serviço público muda o formato de resposta ou sai do ar por algumas horas, o que de vez em quando acontece em qualquer serviço gratuito.

Se o projeto usa várias linguagens ou equipes, padronize também o formato interno do endereço: um mesmo conjunto de campos para todos, independentemente da API de origem. Assim, trocar a fonte não exige reescrever o restante do sistema.

Ao final dos testes, revise também as mensagens exibidas ao usuário. Um texto claro como "não encontramos esse CEP, confira os números ou preencha o endereço manualmente" evita desistências e reduz chamados de suporte. Mensagens técnicas, com códigos de erro ou trechos de resposta, só confundem quem está comprando.

Vale ainda medir quantas consultas retornam erro. Se uma proporção alta de CEPs digitados não é encontrada, pode haver problema na máscara do campo, na limpeza do número ou em uma queda da API. Esse acompanhamento simples ajuda a detectar falhas antes que elas afetem muitos clientes.

Por último, mantenha o código de consulta separado do restante do formulário. Uma função única, com entrada de CEP e saída de endereço, facilita testes, reaproveitamento em outras páginas e troca de API no futuro. É um investimento pequeno que paga rapidamente quando o projeto cresce e novas telas passam a pedir endereço, como cadastro, carrinho, perfil e agendamento de visitas.

Se a sua equipe é pequena, comece pelo caminho mais simples: chamada direta do navegador, validação de formato, tratamento de erro e uma segunda API de reserva. Esse conjunto resolve a grande maioria dos casos e pode evoluir depois, com cache central e monitoramento, conforme o volume de consultas aumentar e a empresa precisar de mais controle sobre a disponibilidade.

Lembre-se, por fim, de que o CEP é apenas uma parte do endereço. Número do imóvel, complemento e ponto de referência continuam sendo digitados pelo usuário, e uma boa interface deixa claro quais campos foram preenchidos automaticamente e quais ainda dependem de informação.

Fonte dos dados de endereço: DNE dos Correios, via ViaCEP (com BrasilAPI como alternativa). O CEP BR é independente e não tem vínculo com os Correios. Veja a metodologia.