Achar o CEP pela rua
Quem não sabe o CEP informa o estado, a cidade e parte do nome da rua, e escolhe na lista. A busca aceita cidade com ou sem acento.
Publicado em .
Fontes oficiais: o CEP nos Correios e os códigos de município do IBGE.
A rota é GET /cep/buscar?uf=&cidade=&logradouro=&limite=. Os três primeiros campos são obrigatórios; o limite vai de 1 a 50 e o padrão é 20.
O código
export async function cepsDaRua(uf, cidade, rua, limite = 20) {
const q = new URLSearchParams({ uf, cidade, logradouro: rua, limite: String(limite) });
const r = await fetch(`https://cep.wortic.com/cep/buscar?${q}`);
const j = await r.json();
if (r.status !== 200) return { erro: j.erro?.codigo || String(r.status), itens: [] };
return { itens: j.itens.map((e) => ({ cep: e.cep_formatado, rua: e.logradouro, complemento: e.complemento, bairro: e.bairro })) };
}
console.log(await cepsDaRua("SP", "São Paulo", "Alexandre Dumas", 3));
O que volta
{ itens: [
{ cep: "04717-000", rua: "Rua Alexandre Dumas", complemento: "", bairro: "Chácara Santo Antônio (Zona Sul)" },
{ cep: "04717-001", rua: "Rua Alexandre Dumas", ... },
{ cep: "04717-002", rua: "Rua Alexandre Dumas", ... } ] }
Uma rua longa pode ter vários CEPs, cada um para um trecho. Mostre o complemento e o bairro na lista para a pessoa escolher o certo.
Os erros da busca
| Resposta | Quando |
|---|---|
400 busca_curta | Rua com menos de 3 letras |
400 uf_invalida | A sigla do estado não existe, como "XX" |
| 422 | Falta uf, cidade ou logradouro, ou o limite está fora de 1 a 50 |
Perguntas e respostas
Quantas letras da rua a busca precisa?
Pelo menos 3. Com menos, a API responde 400 com o código busca_curta.
Preciso escrever a cidade com acento?
Não. "São Paulo" e "sao paulo" dão o mesmo resultado.
O que volta quando nenhuma rua combina?
Uma lista vazia, com status 200: {"itens":[],"total":0}. Erro só quando falta campo, a UF não existe ou a rua é curta.
Todos os guias · Documentação com exemplos em 10 linguagens · openapi.json · Versão para IA