Part of a Data Solution
- Explore →
Postal Codes Solution
Every worldwide postal-code dataset in one bundle — the ultimate global reference for precise postal codes.
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
- Creative Commons Attribution 4.0 — GeoNames (postal codes, place names, administrative names, coordinates, alternative names) license
API Access
Access dataset files directly from scripts, code, or AI agents.
Browse dataset files
API Access
Access dataset files directly from scripts, code, or AI agents.
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.
Start with these files — they give you everything you need to understand and access the dataset.
- 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-pt-sample
| Field | Type | Description | Constraints | Title |
|---|---|---|---|---|
| country_code | string | ISO 3166-1 alpha-2 country code — always PT | { "pattern": "^PT$", "required": true } | Country Code |
| postal_code | string | Portuguese postal code, formatted 'NNNN-NNN' | { "pattern": "^\\d{4}-\\d{3}$", "required": true } | Postal Code |
| place_name | string | Place / locality / street segment name for the postal code | Place Name | |
| admin_name1 | string | District (Distrito) or autonomous region name | Administrative Name 1 | |
| admin_code1 | string | ISO 3166-2:PT code, prefix stripped (01-18, 20, 30) | Administrative Code 1 | |
| admin_name2 | string | Municipality (Concelho) name | Administrative Name 2 | |
| admin_code2 | string | Municipality code (distrito+concelho, 4 digits) | Administrative Code 2 | |
| admin_name3 | string | Parish / locality (Freguesia) name | Administrative Name 3 | |
| admin_code3 | string | Official CAOP DICOFRE parish code: the 4-digit municipality code plus 2 characters (digits, or letters where a municipality has more than 99 parishes, e.g. 0302FA). Empty where neither the parish name nor the coordinate resolves it — see README | Administrative Code 3 | |
| latitude | number | Latitude, decimal degrees (WGS84) | Latitude | |
| longitude | number | Longitude, decimal degrees (WGS84) | Longitude | |
| accuracy | string | GeoNames accuracy of latitude/longitude. GeoNames documents 1=estimated, 4=geonameid, 6=centroid of addresses or shape; other values (e.g. 3) occur upstream without documentation. Empty where GeoNames gives none. | Accuracy | |
| alternative_city_name | string | Alternative or historic name for the place where known, from the GeoNames gazetteer | Alternative City Name |
Download
Download sample CSVAbout
- Last updated
- 6 October 2026
- Total rows
- 100
- Format
- CSV
- File size
- 8.33 kB
About this dataset
Portugal (PT) — internal licensing notes
Not mentioned in datahub-next#941 — no known licensing flag on this country. Sources: GeoNames PT postal export (CC BY 4.0) + CAOP (Carta Administrativa Oficial de Portugal — official Portuguese admin boundary register, DICOFRE crosswalk + freguesia geometry).
Session finding, 2026-08-19
Fixed pt/scripts/ from hardcoded other-repo paths to self-contained.
Verified via a genuinely fresh fetch (all caches deleted first): full
7-stage pipeline (fetch -> build -> DICOFRE enrichment -> spatial join ->
alt-name recovery -> integrity check -> package) produces exactly 14,538
rows, sorted-diff MD5-identical to live R2 (the only pre-sort difference was
non-deterministic tie-break ordering, not a data discrepancy). Rebuilt this
way specifically because the live R2 copy was produced by the same buggy
generic GeoNames-to-R2 script noted for Germany (463/500 sampled PT rows
showed .0-suffixed float-coerced admin codes).
No licensing review beyond confirming the two sources' licences — this was a code-reproducibility audit, not a licence audit.
Licence review — 2026-10-09 (open: share-alike in a sold dataset)
Fixed now: the yaml licenses listed only CC-BY-SA-4.0, though most columns
come from GeoNames (CC BY 4.0). It now lists both.
What the CC BY-SA input contributes: Aldeias Portuguesas core.json supplies only
the official DICOFRE code (admin_code3) and the official freguesia name
(admin_name3). Its geo.geojson boundaries are used only for point-in-polygon
matching inside the build and are not shipped. Aldeias' own field table credits
these to DGAL/INE (codes, names) and DGT CAOP 2025 (boundaries). Its licence section
says the CC BY-SA covers its normalisation and enrichment, and "as bases originais
do INE, DGAL e DGT mantêm as suas condições próprias". Read 2026-10-09 at
https://aldeiasportuguesas.pt/dados/.
Residual risk: CC BY-SA 4.0 §4 covers sui generis database rights. Extracting a substantial portion of the database (we take essentially the full freguesia list) makes our database Adapted Material under a strict reading, which brings share-alike to a sold product. Moderate to low risk.
Clean fix available: DGT publishes CAOP 2025 itself under cc-by on dados.gov.pt
(Continente, RAA and RAM GeoPackages: https://geo2.dgterritorio.gov.pt/caop/CAOP_{Continente,RAA,RAM}_2025-gpkg.zip,
last updated 2026-07-02). Sourcing the codes, names and boundaries from DGT directly
removes share-alike. Not done yet: it is a source switch, and the DGT hosts timed
out from the build machine on 2026-10-09. A switch needs a reachable network and a
parity report against the current data.
Status: decision pending (owner): switch to DGT, keep Aldeias with both licences declared, or make pt free. The 2026-10-05 acceptance of Aldeias (pc-28e.7.59) was a sourcing decision; its licence was not reviewed then.
Owner decision, 2026-10-09: keep the share-alike source
Keep the Aldeias Portuguesas republication (CC BY-SA 4.0) for the freguesia codes and names, declared alongside GeoNames CC BY 4.0, and keep selling at tier C. Switching to DGT CAOP (CC BY) stays available as an optional future improvement, not a requirement. Status: closed by owner decision.