Correios APIempresas.correios.com.br ↗
Look up any Brazilian CEP via the Correios empresas database. Returns street, neighborhood, city, state, IBGE code, DDD, and more in one API call.
What is the Correios API?
The Correios empresas.correios.com.br API provides a single lookup_cep endpoint that resolves any 8-digit Brazilian CEP into 10 structured fields, including street address, neighborhood, city, full state name, two-letter state abbreviation, geographic region, area code (DDD), and administrative codes such as IBGE, SIAFI, and GIA. It covers the full national CEP address database maintained by Correios, Brazil's federal postal service.
curl -X GET 'https://api.parse.bot/scraper/146f901c-9f83-4265-b9cd-c4f69113d7aa/lookup_cep?cep=01310100' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace empresas-correios-com-br-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.correios_cep_lookup_api import Correios, Address, CepNotFound
correios = Correios()
# Look up a CEP by its postal code
address = correios.addresses.get(cep="01310100")
print(address.logradouro, address.localidade, address.uf)
print(address.bairro, address.regiao, address.ddd)
# Use constructible resource for a known CEP, then refresh to hydrate
known = correios.address(cep="20040-020")
full = known.refresh()
print(full.cep, full.logradouro, full.localidade, full.estado)
Look up details for a Brazilian CEP (postal code). Returns the full address information including street name, neighborhood, city, state, region, and administrative codes. The CEP may include or omit the dash separator. Returns input_not_found when the CEP does not exist in the Correios database.
| Param | Type | Description |
|---|---|---|
| ceprequired | string | 8-digit Brazilian CEP code. Dashes are optional (e.g. '01310100' or '01310-100'). |
{
"type": "object",
"fields": {
"uf": "string, two-letter state abbreviation",
"cep": "string, formatted CEP with dash (e.g. '01310-100')",
"ddd": "string, area code (DDD)",
"gia": "string, GIA code",
"ibge": "string, IBGE municipality code",
"siafi": "string, SIAFI code",
"bairro": "string, neighborhood name",
"estado": "string, full state name",
"regiao": "string, geographic region name",
"unidade": "string, postal unit identifier",
"localidade": "string, city name",
"logradouro": "string, street name",
"complemento": "string, address complement or range details"
},
"sample": {
"data": {
"uf": "SP",
"cep": "01310-100",
"ddd": "11",
"gia": "1004",
"ibge": "3550308",
"siafi": "7107",
"bairro": "Bela Vista",
"estado": "São Paulo",
"regiao": "Sudeste",
"unidade": "",
"localidade": "São Paulo",
"logradouro": "Avenida Paulista",
"complemento": "de 612 a 1510 - lado par"
},
"status": "success"
}
}About the Correios API
What the API Returns
The lookup_cep endpoint accepts an 8-digit CEP string — with or without a dash (e.g. 01310100 or 01310-100) — and returns a flat JSON object. Key fields include logradouro (street name), bairro (neighborhood), localidade (city), uf (two-letter state code), estado (full state name), and regiao (macro-geographic region such as Sudeste or Sul). The response also includes cep formatted with a dash for display use.
Administrative Codes
Beyond the human-readable address, each response carries three administrative identifiers that are commonly required in Brazilian government and logistics systems: ibge (the IBGE municipality code used in census and tax contexts), siafi (the federal treasury system code), and gia (the São Paulo state tax authority code, populated where applicable). The ddd field returns the telephone area code for the locality, which is useful when pre-filling phone number forms.
Input Flexibility and Coverage
The single required parameter is cep. Dashes in the input are optional — both formats resolve correctly. The API covers residential, commercial, and PO-box CEP ranges across all 26 Brazilian states and the Federal District. CEPs that do not correspond to a specific street (range-based codes covering entire cities or neighborhoods) will return the locality and state fields without a street name, which is expected behavior for those ranges.
The Correios API is a managed, monitored endpoint for empresas.correios.com.br — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when empresas.correios.com.br changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official empresas.correios.com.br API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Auto-fill checkout address forms by resolving a customer-entered CEP into street, neighborhood, and city fields.
- Validate that a user-supplied CEP exists and belongs to the expected state (
uf) before processing a shipment. - Enrich a customer database with IBGE municipality codes for tax classification or census segmentation.
- Pre-populate the
dddarea code when a user registers a phone number, based on their CEP. - Filter or route logistics orders by
regiao(macro-region) to assign carrier zones. - Attach SIAFI codes to municipal records for integration with federal government financial systems.
- Verify that a billing address CEP matches the
localidadeandufclaimed by the user.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Correios offer an official developer API for CEP lookups?+
What does the lookup_cep endpoint return for a CEP that covers a whole city rather than a specific street?+
logradouro and bairro fields will be empty strings. The localidade, uf, estado, regiao, ibge, siafi, and ddd fields are still populated. This is standard behavior in the Correios database for those code ranges.Does the API return latitude and longitude coordinates for a CEP?+
ibge, siafi, gia, ddd) but no geographic coordinates. You can fork this API on Parse and revise it to add a geocoding step using the returned address fields.Can I look up multiple CEPs in a single request?+
lookup_cep endpoint resolves one CEP per call. Bulk resolution is not currently supported in this API. You can fork it on Parse and revise to add a batch endpoint that accepts an array of CEP values.