Endpoints

Endpoints

Parâmetros

Parameters

Exemplo

Example

curl https://cep.alicercelabs.com.br/api/v1/cep/01310100?ddd=true \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "cep": "01310-100",
    "logradouro": "Avenida Paulista",
    "complemento": "",
    "bairro": "Bela Vista",
    "municipio": "São Paulo",
    "municipio_cod_ibge": 3550308,
    "uf": "SP",
    "ddd": "11"
  },
  "meta": { "elapsed_ms": 2, "request_id": "..." }
}

O campo ddd só aparece com ?ddd=true na URL — sem o parâmetro, a resposta é a mesma de sempre.

The ddd field only shows up with ?ddd=true in the URL — without it, the response is the same as always.

Erros possíveis

Possible errors

Distância entre CEPs

Distance between CEPs

Distância em linha reta (fórmula de Haversine), não rodoviária. O DNE não traz coordenadas, então cada endereço é geocodificado sob demanda — a resposta ainda vem na mesma chamada (SYNC), só que com uma etapa extra na primeira vez que um CEP aparece.

Straight-line distance (Haversine formula), not driving distance. The postal database has no coordinates, so each address gets geocoded on demand — the response still comes back in the same call (SYNC), just with an extra step the first time a given CEP shows up.

curl https://cep.alicercelabs.com.br/api/v1/cep/distance/01310100/20040020?rota=true \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "origem": { "cep": "01310100", "municipio": "São Paulo", "uf": "SP", "lat": -23.5613, "lon": -46.6564 },
    "destino": { "cep": "20040020", "municipio": "Rio de Janeiro", "uf": "RJ", "lat": -22.9068, "lon": -43.1729 },
    "distancia_km": 357.66,
    "distancia_rodoviaria_km": 429.5,
    "duracao_rodoviaria_min": 320.2
  },
  "meta": { "elapsed_ms": 210, "request_id": "..." }
}

Os dois campos rodoviários só aparecem com ?rota=true — sem ele, a resposta traz só distancia_km (linha reta), como antes.

Both road fields only show up with ?rota=true — without it, the response only carries distancia_km (straight-line), as before.

Coordenadas geocodificadas ficam em cache por 6 meses — o endereço de um CEP não muda, então a mesma dupla de CEPs (ou qualquer combinação reaproveitando um deles) fica praticamente instantânea depois da primeira vez. A rota (?rota=true) fica em cache por 30 dias, um pouco menos — estradas mudam mais que endereços.

Geocoded coordinates are cached for 6 months — a CEP's address doesn't change, so the same pair (or any combination reusing one of them) is near-instant after the first time. The road route (?rota=true) is cached for 30 days, a bit less — roads change more than addresses.

Busca reversa, autocomplete e catálogos

Reverse search, autocomplete and catalogs

Três endpoints pra quando você tem o endereço e quer o CEP, não o contrário — todos lendo só do banco local, sem chamada externa. /busca filtra por UF (obrigatória) mais cidade e logradouro opcionais e parciais: o mesmo filtro de logradouro serve tanto pra achar um CEP quanto pra autocompletar conforme o usuário digita. /cidades e /bairros existem pra montar um formulário em duas etapas — escolha a cidade, depois o bairro — sem o cliente ter que adivinhar a grafia exata.

Three endpoints for when you have the address and want the CEP, not the other way around — all reading only from the local database, no outbound call. /busca filters by state (required) plus optional, partial city and street name: the same street-name filter works both for finding a CEP and for autocompleting as someone types. /cidades and /bairros exist to build a two-step form — pick the city, then the neighborhood — without the client having to guess exact spelling.

{
  "success": true,
  "data": [
    { "cep": "01310-100", "logradouro": "Avenida Paulista", "bairro": "Bela Vista", "municipio": "São Paulo", "uf": "SP", ... },
    { "cep": "01311-000", "logradouro": "Alameda Santos", ... }
  ],
  "meta": { "elapsed_ms": 5, "request_id": "..." }
}

Zero resultados é 200 com um array vazio, não 404 — uma busca sem match é uma resposta válida, não um erro.

Zero results is a 200 with an empty array, not a 404 — a search with no matches is a valid outcome, not an error.

Busca em lote

Bulk lookup

POST /api/v1/cep/lote busca vários CEPs numa chamada só — até 50 por lote. A resposta é um array na mesma ordem, cada item com endereco (sucesso) ou erro (formato inválido / não encontrado), nunca os dois.

POST /api/v1/cep/lote looks up several CEPs in one call — up to 50 per batch. The response is an array in the same order, each item carrying either endereco (success) or erro (invalid format / not found), never both.

curl -X POST https://cep.alicercelabs.com.br/api/v1/cep/lote \
  -H "Authorization: Bearer <token>" \
  -d '{"ceps": ["01310100", "20040020", "cep-invalido"]}'

{
  "success": true,
  "data": [
    { "cep": "01310100", "endereco": { "logradouro": "Avenida Paulista", ... } },
    { "cep": "20040020", "endereco": { "logradouro": "Avenida Rio Branco", ... } },
    { "cep": "cep-invalido", "erro": "formato inválido" }
  ],
  "meta": { "elapsed_ms": 9, "request_id": "..." }
}

Importante: um lote de 50 CEPs custa 50 unidades da cota de cep/lote, o mesmo que 50 chamadas separadas a GET /api/v1/cep/{cep} custariam — não 1. Do contrário, dava pra contornar o limite inteiro simplesmente empacotando tudo num lote gigante que "custa" uma chamada só.

Important: a batch of 50 CEPs costs 50 units of the cep/lote quota, the same as 50 separate calls to GET /api/v1/cep/{cep} would — not 1. Otherwise, the entire limit could be sidestepped just by packing everything into one giant batch that "costs" a single call.

Limites

Limits

10.000/dia · 416/hora, por IP chamador, contado separado por operação — lookup, distance, busca, cidades, bairros e lote têm cotas independentes. A exceção é lote: em vez de 1 unidade por chamada, cada CEP dentro do lote consome 1 unidade da cota (ver "Busca em lote" acima). Lookups de endereço, busca, cidades e bairros vêm de um banco local — sem chamada externa. Distância (com ?rota=true) é a exceção que depende de serviços externos configuráveis (padrão grátis, sem chave), com cache de 6 meses/30 dias.

10,000/day · 416/hour, per calling IP, counted separately per operation — lookup, distance, busca, cidades, bairros and lote have independent quotas. The exception is lote: instead of 1 unit per call, each CEP inside the batch consumes 1 unit of the quota (see "Bulk lookup" above). Address lookups, search, cities and neighborhoods come from a local database — no outbound call. Distance (with ?rota=true) is the exception depending on configurable external services (default is free, no key), cached for 6 months/30 days.