CEP Lookup - Brazil Address Finder

Look up Brazilian postal codes (CEP) and get complete address data instantly. FREE, real-time, no API key needed.

What it does

This Actor receives one or more Brazilian CEPs (postal codes) and returns full address details including street, neighborhood, city, state, IBGE code, DDD (area code), and coordinates when available.

• Queries ViaCEP (primary) and BrasilAPI (fallback)
• Supports batch lookups: up to 100 CEPs per run
• Returns coordinates (latitude/longitude) via BrasilAPI
• Automatic CEP validation and formatting
• Rate-limited to respect API fair use

Input

Field	Type	Description
ceps	string[]	Array of CEP numbers (up to 100)
cep	string	Single CEP number
useFallback	boolean	Try BrasilAPI if ViaCEP fails (default: true)

CEPs can be provided with or without formatting:

• 01001000 or 01001-000 both work
• Non-digit characters are automatically stripped

Output

Each result includes:

Field	Description
cep	CEP (8 digits)
cep_formatado	Formatted CEP (XXXXX-XXX)
logradouro	Street name
complemento	Address complement
bairro	Neighborhood
cidade	City
estado	State (UF, 2 letters)
ibge	IBGE municipality code
ddd	Area code
siafi	SIAFI code
latitude	Latitude (BrasilAPI only)
longitude	Longitude (BrasilAPI only)
source	Data source: viacep or brasilapi
status	success or error

Example input

{
  "ceps": ["01001000", "20040020", "70040010"],
  "useFallback": true
}

Example output

{
  "cep": "01001000",
  "cep_formatado": "01001-000",
  "logradouro": "Praca da Se",
  "complemento": "lado impar",
  "bairro": "Se",
  "cidade": "Sao Paulo",
  "estado": "SP",
  "ibge": "3550308",
  "ddd": "11",
  "siafi": "7107",
  "latitude": null,
  "longitude": null,
  "source": "viacep",
  "status": "success"
}

Use cases

• E-commerce checkout: Auto-fill address fields when the customer types a CEP
• Address validation: Verify that a CEP exists and matches the expected city/state
• Logistics and shipping: Enrich delivery data with IBGE codes and coordinates
• CRM enrichment: Complete partial address records with full postal data
• Market research: Map CEPs to regions, states, and area codes

Data sources

1. ViaCEP (https://viacep.com.br) - Primary source. Free, public, no API key. Returns street, neighborhood, city, state, IBGE, DDD, SIAFI.
2. BrasilAPI (https://brasilapi.com.br) - Fallback source. Free, public, no API key. Also returns latitude/longitude coordinates when available.

Cost

This Actor uses only free, public APIs. There is no cost beyond Apify platform compute usage.

Limits

• Maximum 100 CEPs per run
• 100ms delay between requests to respect API rate limits
• 15-second timeout per API request

---

Built by NomePronto - Registre sua marca com seguranca.