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 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-it-sample
| Field | Type | Description | Constraints | Title |
|---|---|---|---|---|
| country_code | string | ISO 3166-1 alpha-2 country code — always IT | { "pattern": "^IT$", "required": true } | Country Code |
| postal_code | string | 5-digit Italian postal code (CAP) | { "pattern": "^\\d{5}$", "required": true } | Postal Code |
| place_name | string | Comune or locality name as supplied by the source | Place Name | |
| admin_name1 | string | Region name (Regione), as spelled by the source — see README | Administrative Name 1 | |
| admin_code1 | string | Official ISO 3166-2:IT region code, prefix stripped — derived from the region name, not taken from the source's own field | { "pattern": "^\\d{2}$" } | Administrative Code 1 |
| admin_name2 | string | Province name (Provincia) | Administrative Name 2 | |
| admin_code2 | string | 2-letter province sigla (e.g. MI, RM, NA) | { "pattern": "^[A-Z]{2}$" } | Administrative Code 2 |
| admin_name3 | string | Not provided by this source — always blank | Administrative Name 3 | |
| admin_code3 | string | Not provided by this source — always blank | 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 | Alternative City Name |
Download
Download sample CSVAbout
- Last updated
- 6 October 2026
- Total rows
- 100
- Format
- CSV
- File size
- 6.96 kB
About this dataset
Italy (IT): 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.28 (closed 2026-10-03)
- Commit:
e76c938(worktree commite56c425), landed in batch 4 - Parity verdict:
format-only(CRLF → LF), passing under the standing rule - Producer:
custom, refresh disabled
Sources
| Input | URL | Notes |
|---|---|---|
| GeoNames postal export | https://download.geonames.org/export/zip/IT.zip | The only input |
The ISO 3166-2:IT region codes were never fetched by the old builder. They are a hardcoded 20-region table (checked against en.wikipedia.org/wiki/ISO_3166-2:IT on 2026-08-13), now ISO_BY_REGION_NAME in produce.py.
Parity against the live zip (2026-10-03)
Rows: 18,415 live and 18,415 fresh, none only on one side, 0 changed cells, same row order. The only difference is line endings (live CRLF, 1,237,820 bytes; fresh LF, 1,219,404 bytes).
Decisions
| Decision | By | Basis |
|---|---|---|
| Accept the CRLF → LF change | Standing rule (row_order/CRLF-only, user, 2026-10-02) | Recorded in the batch 4 sign-off in docs/parity/p5.md |
Keep the region crosswalk in produce.py, no reference file | Agent | It was a hardcoded table in the old builder too |
README: the note that admin_code1 has a leading zero (read as text) now points to postal_code instead (e.g. Roma 00118) | Agent: wrong advice fixed | Italian ISO region codes run 21–88 and have no leading zero |
Drop fetch_source.py, build_base.py, integrity_checker.py, package.py, publish_r2.py, scripts/README.md | Agent | Folded into the producer or replaced by build.py |
| Add the stale "Last updated: 2026-08-13" README line to pc-hfz | Orchestrator instruction | The agent flagged it; the orchestrator added a comment to pc-hfz rather than editing it now |
Transforms carried over (unchanged)
Folded from fetch_source.py → build_base.py → integrity_checker.py → package.py:
admin_code1= official ISO 3166-2:IT region code without "IT-", looked up by region name using GeoNames' spellings ("Abruzzi", "Friuli-Venezia Giulia", "Valle D'Aosta"). GeoNames' own alphabetical 01–20 code is dropped.- Province sigla, names and coordinates kept as GeoNames gives them;
alternative_city_nameempty. - Stable sort by (admin_code1, admin_code2, postal_code, place_name).
- The old integrity checks are
ProducerErrors: 5-digit CAP, known region name, 2-letter sigla, no literal "nan", no float accuracy, coordinates inside Italy's bounding box, all 20 regions present, unique (postal_code, place_name). No row-count assert.
Open questions
- The README's hardcoded "Last updated: 2026-08-13" line is left for the pc-hfz sweep, along with any other counts.
Provenance
Reconstructed 2026-10-05 from the agent transcript d33e1b7e-5027-498a-a97f-ba914ee2524e/subagents/agent-a036230ea716ace28.jsonl, the orchestrator session d33e1b7e-…, the commit message, the bd close reason and the batch 4 sign-off in docs/parity/p5.md.