Part of a Data Solution

Postal Codes Solution
Every worldwide postal-code dataset in one bundle — the ultimate global reference for precise postal codes.
Explore →

Premium

You're viewing a free sample

Get the complete dataset — all rows and files — delivered instantly after checkout, with lifetime access to the latest version.

Secure checkout via Stripe
Instant download after payment
Lifetime access to the latest version
MIT License license

20% off

$49.90$39.92

one-time payment

Download sample · CSV · 7.47 kB Report an Issue

API Access

Access dataset files directly from scripts, code, or AI agents.

Browse dataset files

Dataset Files

Each file has a stable URL (r-link) that you can use directly in scripts, apps, or AI agents. These URLs are permanent and safe to hardcode.

/logistics/postal-codes-br/

├ .licensing-notes.md

https://datahub.io/logistics/postal-codes-br/_r/-/.licensing-notes.md

├ .migration-notes.md

https://datahub.io/logistics/postal-codes-br/_r/-/.migration-notes.md

├ ATTRIBUTION.txt

https://datahub.io/logistics/postal-codes-br/_r/-/ATTRIBUTION.txt

├ README.md

https://datahub.io/logistics/postal-codes-br/_r/-/README.md

└ datapackage.yaml

https://datahub.io/logistics/postal-codes-br/_r/-/datapackage.yaml

Key Files

Start with these files — they give you everything you need to understand and access the dataset.

datapackage.yaml— metadata & schema

https://datahub.io/logistics/postal-codes-br/_r/-/datapackage.yaml

README.md— documentation

https://datahub.io/logistics/postal-codes-br/_r/-/README.md

Typical Usage

1. Fetch datapackage.yaml to inspect schema and resources
2. Download data resources listed in datapackage.yaml
3. Read README.md for full context

Data Files

postal-codes-br-sample

Field	Type	Description	Constraints	Title
country_code	string	ISO 3166-1 alpha-2 country code — always BR	{ "pattern": "^BR$", "required": true }	Country Code
postal_code	string	Brazilian CEP, format NNNNN-NNN (full 8-digit code)	{ "pattern": "^\\d{5}-\\d{3}$", "required": true }	Postal Code
place_name	string	Bairro (neighborhood) — the CEP system's sub-municipal delivery unit		Place Name
admin_name1	string	State or Federal District name (Estado / Distrito Federal)		Administrative Name 1
admin_code1	string	ISO 3166-2:BR state code, BR- prefix stripped (e.g. SP, RJ, DF)		Administrative Code 1
admin_name2	string	Municipality name (Município)		Administrative Name 2
admin_code2	string	IBGE municipality code (7-digit)		Administrative Code 2
admin_name3	string	Bairro (neighborhood) — same value as place_name		Administrative Name 3
admin_code3	string	Reserved — no bairro-level code exists in any source		Administrative Code 3
latitude	number	Latitude coordinate (WGS84, decimal degrees) — not available for BR		Latitude
longitude	number	Longitude coordinate (WGS84, decimal degrees) — not available for BR		Longitude
accuracy	string	Coordinate accuracy tier — not available for BR		Accuracy
alternative_city_name	string	Full compound bairro name where the source assigns one CEP to a zone spanning two former neighborhoods (e.g. 'Jardim Monte Cristo/Parque Oziel'); place_name carries only the first component		Alternative City Name

Download

Download sample CSV

About

Last updated: 12 October 2026
Total rows: 100
Format: CSV
File size: 7.47 kB
Sources: SeuAliado/OpenCEP (MIT License) — primary bulk CEP data; Mendeley Data, "Códigos de CEP do Brasil por UF, CIDADE, BAIRRO E LOGRADOURO" by Ivan Zimmermann (CC BY 4.0) — secondary CEP data, consolidated for coverage; IBGE Localidades API — official state and municipality reference; kelvins/municipios-brasileiros (MIT License) — municipality dictionary
License: MIT License

About this dataset

Brazil (BR) — internal licensing notes

Not mentioned in datahub-next#941 — no known licensing flag on this country from that issue, but it has its own real, disclosed licensing caveat found independently this session (below) — worth cross-referencing against #941's general framework (a scraped-source-with-no-stated-licence risk, same shape as several items in #941 §2/§3).

Sources and licences

SeuAliado/OpenCEP (MIT) — primary bulk CEP data. Confirmed via the repo's own LICENSE file; actively maintained (updated the same week this was checked), 401 stars.
Mendeley Data, "Códigos de CEP do Brasil por UF, CIDADE, BAIRRO E LOGRADOURO" by Ivan Zimmermann (CC BY 4.0, confirmed via the dataset page) — secondary CEP data, consolidated for coverage. Data current through 2018.
IBGE Localidades API — official Brazilian government admin reference.
kelvins/municipios-brasileiros (MIT) — municipality dictionary.
ruacep.com.br scrape (~7,000 of 1,233,231 rows) — no stated data-reuse licence. The site is copyrighted ("todos os direitos reservados") with no published reuse terms, confirmed by direct check of its footer/ToS links. This slice cannot be cleanly separated back out of the already-merged dataset without re-deriving from the other four sources individually. Disclosed as a residual, non-blocking risk in research.json and the shipped README — a human decision on whether to accept, exclude, or force a re-derivation is still open.

Given this shape — a multi-source consolidation with one real unresolved licensing caveat on part of the data — this is priced Tier A ($99) per docs/PRICING_TIERS.md's own decision rule, the same category as Canada's pre-#941 situation (base + crosswalk + a licensing caveat no other field carries).

Session finding, 2026-08-19

The real generator script (brazil_postal_code_parse.py) only ever existed in a separate repo (datopian/Fedex-dataset), never committed to either repo touched this session — pulled in along with its two small archive dependencies specifically so this repo doesn't depend on that other repo surviving. Verified the postal-codes-product conversion is SHA256-identical to what's live on R2: 1,233,231 rows (the one postalCode "00000" backfill row, a municipality with no CEP in any source, correctly excluded — this product is a list of postal codes).

Two live-fetch reliability bugs found and fixed in the generator script itself while re-running it self-contained (network issues, unrelated to the licensing question): Mendeley's Cloudflare front 403s requests/urllib3 via TLS fingerprinting regardless of User-Agent header; the 342MB OpenCEP zip has no retry/resume in requests (a single dropped connection loses the whole download). Both switched to curl.

This session's self-containment fix was validated statically, not via a second full live re-fetch (the OpenCEP download proved unreliable over this connection even with retries) — the underlying transformation logic is unchanged from the version that WAS already verified SHA256-identical earlier the same day; only paths and fetch-reliability code changed. See scripts/README.md for the full reasoning.

CLOSED — 2026-08-24 (datahub-next#941 §4)

Added standalone br/ATTRIBUTION.txt mirroring the README's existing "Data Sources" section (SeuAliado/OpenCEP MIT, Mendeley Data CC BY 4.0, IBGE official, kelvins/municipios-brasileiros MIT, plus the ruacep.com.br chain-of-title caveat) — now in R2 and inside br.zip. build_postal_codes_product.py updated to write and zip it, publish_r2.py updated to upload it, on every run. _meta/catalog.json's BR entry rebuilt to include it. No pre-existing defect found.

2026-10-12 — ruacep.com.br dependency measured (P5 producer, issue #41)

The "~7,000 of 1,233,231 rows" above is not what the data shows. Against the live br.csv, 173 rows (0.014%) exist only because of the ruacep.com.br scrape (Mineiros GO 103, Picos PI 35, Ubá MG 15, São Pedro da Aldeia RJ 13, Vinhedo SP 7). A further 8,951 live rows have a CEP that is also in the scrape but are reproduced identically from OpenCEP and Mendeley without it. The new scripts/produce.py does not read the scrape and is 0.036% from live in total. Whether to republish without those 173 rows, and what the README and ATTRIBUTION caveat should then say, is still the owner's decision. See .migration-notes.md.

2026-10-12 — caveat removed, MIT notices added (owner instruction)

The README and ATTRIBUTION caveat about "a small subset of rows … from a community site" is removed: the producer does not read the ruacep.com.br scrape, and the republished br.csv contains none of the 173 rows that depended on it (owner accepted the 0.036% difference to the previous live file). ATTRIBUTION now reproduces the MIT copyright notices and permission text of SeuAliado/OpenCEP (Copyright (c) 2023 Seu Aliado) and kelvins/municipios-brasileiros (Copyright (c) 2016 Kelvin S. do Prado), read from their LICENSE files on GitHub main on 2026-10-12; the two licence bodies are identical. Not changed: IBGE is credited but no explicit IBGE reuse licence has been recorded here.