Construa com endereços do Brasil.

Crie uma conta e uma API key

Crie uma conta, escolha um plano publicado no catálogo e gere uma chave no portal do cliente. A chave completa aparece somente no momento da criação.

Autenticação

Os endpoints protegidos aceitam uma chave em um destes headers. O health check e o readiness são públicos.

X-API-Key: SUA_API_KEY
Authorization: Bearer SUA_API_KEY

A API não aceita chaves em query string. Respostas sem credencial retornam 401 authentication_required; credenciais inválidas retornam 401 invalid_api_key.

Primeira requisição

Use o exemplo abaixo com uma chave ativa. A URL dos exemplos vem da configuração BRASILADDRESS_API_PUBLIC_BASE_URL.

curl --fail-with-body --connect-timeout 5 --max-time 15 \
  -H "X-API-Key: SUA_API_KEY" \
  https://brasiladdress.io/api/v1/cep/01001000

Interpretando a resposta

As consultas retornam um envelope JSON. data contém os registros; meta informa página, limite, ambiguidade ou cobertura quando aplicável.

{
  "data": [{
    "street": "Praça da Sé",
    "district": "Sé",
    "city": "São Paulo",
    "uf": "SP",
    "ibge_code": 3550308,
    "cep": "01001000",
    "number": null,
    "latitude": null,
    "longitude": null,
    "precision": null,
    "source": "base nacional"
  }],
  "meta": {"count": 1}
}

Quotas e rate limiting

Cada requisição autenticada reserva uma unidade da quota mensal da assinatura e passa pelo limite de requisições por minuto mais o burst contratado. Ao exceder um limite, a API responde 429 e envia Retry-After.

Erros HTTP

{"error":{"code":"invalid_query","message":"q deve ter ao menos 3 caracteres."}}

Versionamento e formato

O contrato atual vive em /api/v1. Respostas são JSON UTF-8 e os filtros de texto são normalizados para busca. O campo source e a observação de cobertura ajudam a interpretar a procedência dos registros.

Endpoints

Esta lista é derivada dos controllers reais. Use o explorer para preencher parâmetros e executar uma chamada manual.

Exemplos executáveis

Todos os exemplos usam a mesma API REST e tratam timeout, erros de HTTP e 429. Substitua a variável de ambiente pela chave armazenada no seu ambiente seguro.

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 15000);
const response = await fetch(`${BASE_URL}/api/v1/cep/01001000`, {
  headers: { 'X-API-Key': process.env.BRASILADDRESS_API_KEY },
  signal: controller.signal
});
clearTimeout(timer);
if (response.status === 429) throw new Error(`Retry after ${response.headers.get('Retry-After')}s`);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

import os, httpx

with httpx.Client(timeout=15) as client:
    response = client.get(
        os.environ["BRASILADDRESS_BASE_URL"] + "/api/v1/cep/01001000",
        headers={"X-API-Key": os.environ["BRASILADDRESS_API_KEY"]},
    )
    if response.status_code == 429:
        raise RuntimeError("Aguarde o Retry-After antes de tentar novamente")
    response.raise_for_status()
    print(response.json())

$ch = curl_init(getenv('BRASILADDRESS_BASE_URL').'/api/v1/cep/01001000');
  CURLOPT_HTTPHEADER => ['X-API-Key: '.getenv('BRASILADDRESS_API_KEY')],
  CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status === 429) throw new RuntimeException('Respeite Retry-After');
if ($status >= 400) throw new RuntimeException($body ?: curl_error($ch));
echo $body;

Planos e limites

Os valores abaixo são carregados do catálogo de planos publicados, o mesmo usado na página comercial e administrado em /admin/planos.

OpenAPI, Swagger UI e ReDoc

A especificação é gerada pelo contrato da aplicação e alimenta as três interfaces. Baixe o formato que preferir ou abra uma ferramenta interativa.

Status e suporte: use o health check para monitoramento técnico e o portal do cliente para consumo, chaves e assinatura.

TypeScript

O exemplo usa fetch, timeout e tratamento explícito de HTTP 429.

const response = await fetch(`${process.env.BRASILADDRESS_BASE_URL}/api/v1/cep/01001000`, {
  headers: { 'X-API-Key': process.env.BRASILADDRESS_API_KEY ?? '' },
  signal: AbortSignal.timeout(15000),
});
if (response.status === 429) throw new Error(`Retry-After: ${response.headers.get('Retry-After')}`);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());