Skip to main content

​
Endpoint

GET https://api.bunny.build/api/v1/cep-lookup/:cep

​
Authentication

HeaderRequiredValue
X-API-KeyYesYour API key (bun_...)

​
Overview

Resolve any Brazilian postal code (CEP) to a full address instantly. Bunny’s CEP API returns street name, neighborhood, city, and state for any valid 8-digit CEP, with no formatting required.

​
Use cases

  • Auto-fill address forms on checkout
  • Validate shipping destinations
  • Enrich customer records with location data
  • Build delivery area maps

​
Details

Strip hyphens before passing the CEP. Accepts 01310100 or 01310-100. Both work. Returns null fields for CEPs that cover an entire municipality with no specific street.

​
Path parameters

ParameterTypeRequiredDescription
cepstringYesBrazilian postal code (CEP), digits only (e.g. 01310100)

​
Response

​
200 OK

FieldTypeDescription
cepstringThe CEP that was looked up (digits only)
logradourostringStreet name
complementostringAddress complement (may be empty)
bairrostringNeighborhood
cidadestringCity name
ufstringState abbreviation (e.g. SP)
estadostringFull state name (e.g. São Paulo)
regiaostringBrazilian region (e.g. Sudeste, Nordeste)
Example 
{
  "cep": "01310100",
  "logradouro": "Avenida Paulista",
  "complemento": "de 1 a 610 - lado par",
  "bairro": "Bela Vista",
  "cidade": "São Paulo",
  "uf": "SP",
  "estado": "São Paulo",
  "regiao": "Sudeste"
}

​
401 Unauthorized

{
  "detail": "Missing API key. Include X-API-Key header."
}

​
402 Payment Required

{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}

​
404 Not Found

CEP not found. 
{
  "detail": "CEP not found"
}

​
422 Unprocessable Entity

Invalid CEP format. 
{
  "detail": "Invalid CEP format"
}

​
429 Too Many Requests

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

​
cURL example

curl https://api.bunny.build/api/v1/cep-lookup/01310100 \
  -H "X-API-Key: bun_your_api_key"