empresas.correios.com.br 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.
curl -X GET 'https://api.parse.bot/scraper/146f901c-9f83-4265-b9cd-c4f69113d7aa/lookup_cep?cep=20040020' \ -H 'X-API-Key: $PARSE_API_KEY'
Look up details for a Brazilian CEP (postal code). Returns the full address information including street name, neighborhood, city, state, region, and administrative codes.
| 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",
"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 empresas.correios.com.br 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.
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.
- 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 | 250 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.