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
Creative Commons Attribution 4.0 International license

20% off

$49.90$39.92

one-time payment

Download sample · CSV · 5.73 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-pr/

├ .licensing-notes.md

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

├ .migration-notes.md

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

├ ATTRIBUTION.txt

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

├ README.md

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

└ datapackage.yaml

https://datahub.io/logistics/postal-codes-pr/_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-pr/_r/-/datapackage.yaml

README.md— documentation

https://datahub.io/logistics/postal-codes-pr/_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-pr-sample

Field	Type	Description	Constraints	Title
country_code	string	ISO 3166-1 alpha-2 -- always PR		Country Code
postal_code	string	US ZIP code (5 digits, leading zero significant -- 006xx / 007xx / 009xx)	{ "pattern": "^\\d{5}$" }	Postal Code
place_name	string	Post office / locality name		Place Name
admin_name1	string	Municipio -- all 78 covered		Administrative Name 1
admin_code1	string	Census FIPS county-equivalent code for the municipio (5 digits, state prefix 72). NOT an ISO 3166-2 code -- ISO 3166-2 defines no subdivisions for Puerto Rico.	{ "pattern": "^72\\d{3}$" }	Administrative Code 1
admin_name2	string	Not populated -- Puerto Rico has one sub-territorial admin tier		Administrative Name 2
admin_code2	string	Not populated		Administrative Code 2
admin_name3	string	Not populated		Administrative Name 3
admin_code3	string	Not populated		Administrative Code 3
latitude	number	GeoNames latitude (WGS84)		Latitude
longitude	number	GeoNames longitude (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	Not populated in this release		Alternative City Name

Download

Download sample CSV

About

Last updated: 2 October 2026
Total rows: 100
Format: CSV
File size: 5.73 kB
Source: GeoNames postal code database -- Puerto Rico (PR)
License: Creative Commons Attribution 4.0 International

About this dataset

Puerto Rico (PR): migration notes

Internal record of the P5 migration from the old scripts to the producer: the discrepancies found, their causes, and who decided what. This is a dated record, so the numbers are as of the migration and not kept current. It is not shipped in the zip.

Issue: pc-28e.7.46 (closed 2026-10-02)
Commit: 7c3cfc1 (worktree commit 82b1183), landed in batch 3
Parity verdict: format-only (gate passes)
Producer: custom, refresh disabled

Sources

Input	URL	Notes
GeoNames postal export	https://download.geonames.org/export/zip/PR.zip	The only input; same URL as the old builder

The US Census ZCTA Gazetteer would be preferable, but on 2026-09-16 census.gov returned HTTP 403 and api.census.gov needs a key (see .licensing-notes.md). It also has no place or municipio names.

Parity against the live zip (2026-10-02)

Rows: 177 live and 177 fresh, none only on one side, 0 changed cells. With CRs stripped, the fresh CSV is byte-identical to live. The only difference is CRLF→LF. The informational sample check was also format-only.

Decisions

Decision	By	Basis
Accept CRLF→LF	Standing rule (line-ending-only, user, 2026-10-02)	`format-only` passes the gate
`admin_code1` is the 5-digit Census FIPS code, not an ISO code	Agent: a faithful port	ISO 3166-2 defines no PR subdivisions
Refuse postal codes that aren't `00[679]NN` instead of padding them	Agent: a faithful port	The old builder asserted the source keeps the leading zero
Remove row, distinct-code and "0 collisions" counts from README and description; keep "78 municipios"	Orchestrator instruction (README counts rule, plan §4 P5)	Counts drift

Transforms carried over

From build_postal_codes_product.py (now removed, with publish_r2.py):

postal_code keeps its leading zero; anything not 5 digits starting 006/007/009 is a ProducerError.
admin_code1 = "72" + GeoNames' 3-digit municipio code. The 3-digit codes must match the PR county-equivalent roster (odd 001–153 plus 054), every municipio must be present, and name↔code must be 1:1.
admin_name2/code2/name3/code3 are empty: a literal "nan" is blanked, any other value is refused.
alternative_city_name is empty.
The old asserts are now ProducerErrors; unique (postal_code, place_name) and non-empty coordinates are checked. No row-count assert.

Open questions

.licensing-notes.md still contains counts ("176 rows", a stale historical figure); it is left for the end-of-epic sweep (pc-hfz).

Provenance

Reconstructed 2026-10-05 from the agent transcript 2479b1c9-c4dd-47e5-be82-34ccf8d49a80/subagents/agent-a76af718598b67a36.jsonl (the run was cut off by a rate limit and resumed), the orchestrator session 2479b1c9-…, the commit message, docs/parity/p5.md and the bd close reason.