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 International 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-al-sample
| Field | Type | Description | Constraints | Title |
|---|---|---|---|---|
| country_code | string | ISO 3166-1 alpha-2 -- always AL | Country Code | |
| postal_code | string | Albanian postal code (4 digits) | { "pattern": "^\\d{4}$" } | Postal Code |
| place_name | string | Locality/place name as GeoNames records it | Place Name | |
| admin_name1 | string | Qark (county) -- 12/12 covered | Administrative Name 1 | |
| admin_code1 | string | ISO 3166-2:AL code | Administrative Code 1 | |
| admin_name2 | string | Bashki (municipality) -- 31 of 61 covered (GeoNames' own coverage gap, not introduced by this build) | Administrative Name 2 | |
| admin_code2 | string | Not populated -- Albania has no official short code for bashki; a GeoNames-internal id is deliberately not substituted here | Administrative Code 2 | |
| admin_name3 | string | Not available -- no sellable source reaches this tier (njesi administrative), see .licensing-notes.md | Administrative Name 3 | |
| admin_code3 | string | Not available | Administrative Code 3 | |
| latitude | number | GeoNames-estimated latitude (WGS84) | Latitude | |
| longitude | number | GeoNames-estimated 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 | First alternate name GeoNames records, where one exists | Alternative City Name |
Download
Download sample CSVAbout
- Last updated
- 2 October 2026
- Total rows
- 100
- Format
- CSV
- File size
- 8.08 kB
About this dataset
Albania (AL): 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.1 (closed 2026-10-02)
- Commit:
aaf91aa(worktree commitf65d926, same content), landed in batch 1 - Parity verdict:
explained(row_orderonly); user signed off 2026-10-02 - Producer:
custom, refresh disabled
Sources
| Input | URL | Notes |
|---|---|---|
| GeoNames postal export | https://download.geonames.org/export/zip/AL.zip | |
| GeoNames gazetteer dump | https://download.geonames.org/export/dump/AL.zip | Used for alternative_city_name, as in the old builder |
Parity against the live zip (2026-10-02)
Rows: 494 live and 494 fresh, none only on one side. 0 changed cells. One class: row_order ×1. Apart from that order and the line endings (live CRLF, fresh LF), the fresh CSV is byte-identical to live.
| Change | Cause |
|---|---|
| The four rows of postal code 8706 (Margegaj, Lekbibaj, Llugaj, Bujan; Bashkia Tropojë) come out in a different order | Attributed to GeoNames reordering its export. Not traced to a specific earlier GeoNames file |
The public sample at postal.datahub.io/al/al.csv came out unexplained (informational only: unclassified ×196, float_suffix_dropped ×93). It predates the old builder's fixes and gets replaced on the first post-merge publish.
Decisions
| Decision | By | Basis |
|---|---|---|
Accept row_order | User, 2026-10-02 (session 2479b1c9) | "I sign off on the row order"; recorded in the sign-off section of docs/parity/p5.md |
| Alternate names: the first matching dump entry wins, no name cleaning | Agent: a faithful port | The old builder did this; the shared geonames producer lets the last entry win and cleans names |
| Remove row, distinct-code and "283/494 rows" counts from README and descriptor; keep "12 qark" and "31 of 61 bashki" | Orchestrator instruction | README counts rule (user, 2026-10-02, session 068ca403) |
| No exact row-count assert | Orchestrator instruction | Batch brief |
| Accuracy description replaced with the shared GeoNames wording | Orchestrator, after the user's "fix the small doc problems" (session 2479b1c9) | The agent flagged that the old "1/4/6" text didn't match the data (empty, 1, 3, 4). b7fb93b, 5311ad3 |
Transforms carried over
From build_postal_codes_product.py:
admin_code1→ ISO 3166-2:AL via the qark-name crosswalk (checked against Wikipedia 2026-08-28), replacing GeoNames' FIPS-style "40"–"51".admin_name1"Tirana" → "Qarku i Tiranës".admin_code2emptied (GeoNames puts a geonameid there).alternative_city_name: first non-empty, non-numeric alternate of the first dump entry whose asciiname equalsplace_name.- Cells copied verbatim (no "nan", no "4.0").
- Old asserts are
ProducerErrors: wrong shape or country, unknown qark, non-4-digit code, "nan" or float accuracy, duplicate (postal_code, place_name), any of the 12 qark missing.
Open questions
- Resolved (2026-10-05, pc-28e.7.60): added the GeoNames dump to
sources. Was:datapackage.yamlsourceslists only the postal export, not the GeoNames dump the producer also fetches. ATTRIBUTION.txtstill says "494 rows"; 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-a52463d84efdec800.jsonl, the orchestrator sessions 2479b1c9-… (batch 1, sign-off) and 068ca403-… (README counts rule), the commit message and the bd close reason.