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.
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
Explore with AIpostal-codes-hk
| Field | Type | Description | Title |
|---|---|---|---|
| country_code | string | ISO 3166-1 alpha-2 code for the country. | Country Code |
| postal_code | string | Always empty: Hong Kong has no postal code system. | Postal Code |
| place_name | string | Name of the city, town, or place. | Place Name |
| admin_name1 | string | District (one of the 18 districts of Hong Kong). Empty where GeoNames assigns the place to no district. | Administrative Name 1 |
| admin_code1 | string | Always empty: Hong Kong has no ISO 3166-2 subdivision codes. | Administrative Code 1 |
| admin_name2 | string | Secondary administrative division (e.g., county, district). | Administrative Name 2 |
| admin_code2 | string | Code for the secondary administrative division. | Administrative Code 2 |
| admin_name3 | string | Tertiary administrative division (e.g., municipality, borough). | Administrative Name 3 |
| admin_code3 | string | Code for the tertiary administrative division. | Administrative Code 3 |
| latitude | number | Latitude coordinate of the place. | Latitude |
| longitude | number | Longitude coordinate of the place. | Longitude |
| accuracy | string | Always empty: the GeoNames gazetteer dump carries no accuracy value. | Accuracy |
| alternative_city_name | string | Alternative name(s) for the city or place. | Alternative City Name |
Download
Download CSVAbout
- Last updated
- 6 October 2026
- Total rows
- 1,342
- Format
- CSV
- File size
- 68.2 kB
About this dataset
Hong Kong (HK): migration notes
Internal record of the P6 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.
- Issue: pc-28e.8.11
- Parity verdict:
format-only(gate: pass), against the live public CSV - Producer:
custom, refresh disabled
Sources
| Input | URL | Notes |
|---|---|---|
| GeoNames gazetteer dump | https://download.geonames.org/export/dump/HK.zip | HK.txt; feature class P only. Stable, unversioned URL |
| GeoNames admin1 table | https://download.geonames.org/export/dump/admin1CodesASCII.txt | Only used to check the 18 HK buckets still match the district crosswalk. Stable, unversioned URL |
Both are the inputs the old build_postal_codes_product.py read from sources/ (HK.txt, geonames_admin1CodesASCII.txt); its docstring names these URLs. The GeoNames postal export (export/zip/HK.zip, a single China Post "999077" placeholder row) is deliberately not used, as before.
Parity against the live public CSV (2026-10-05)
Rows: 1,342 live and 1,342 fresh, none only on one side, 0 changed cells, no cell classes. The fresh CSV is byte-identical to live once live's CRLF line endings are turned into LF (live sha256 f77dd16d…, fresh 5fe50c72…). GeoNames' HK dump (Last-Modified 2026-10-05) has not drifted for populated places since the 2026-09-17 build.
Decisions
| Decision | By | Basis |
|---|---|---|
| Accept the CRLF→LF difference | Standing rule (row_order/CRLF-only, user) | 0 changed cells, equal rows |
pipeline.postal_code_required: false | Agent | build.py refuses empty postal codes otherwise; Hong Kong has no postcode system, so postal_code is empty on every row by design (old builder asserted the same) |
primaryKey: [place_name, latitude, longitude] | Agent, from the produced CSV | Unique in the produced CSV; it is the key the old builder asserted and declared in its datapackage.json |
latitude/longitude → number; accuracy stays string | Agent, from the produced CSV | Coordinates all parse as numbers; accuracy is empty on every row (the gazetteer dump has no accuracy scale), so it is not numeric. The standard GeoNames accuracy description doesn't apply |
Unknown admin1 bucket (other than 00/blank) is a ProducerError | Agent | The old builder only checked the admin1 table; a dump row on an unknown bucket would have silently got an empty district |
| Exact row-count asserts (1,342 places, 71 unresolved) dropped | Brief rule | Structural checks kept instead: the bucket set matches the crosswalk, every district has a place, PK unique, no nan, no empty place_name |
Transforms carried over
From build_postal_codes_product.py (2026-09-17):
- Feature class
Ponly;place_nameis GeoNamesname; coordinates copied verbatim as text. postal_codeandadmin_code1empty on every row (no postcode system; no ISO 3166-2:HK subdivisions).admin_name1from the GeoNames bucket via the 18-entry district crosswalk (plain names, GeoNames' "District" suffix dropped). Buckets00and blank get an empty district.- Other admin columns,
accuracyandalternative_city_nameempty. - Sorted by (admin_name1, place_name), ties in GeoNames file order.
Not ported: the old builder's generated datapackage.json, README, ATTRIBUTION and zip (build.py and the descriptor own those now); publish_r2.py.
Doc edits
- Descriptor
description: removed the locality count ("1,342 localities" → "localities"); kept "all 18 districts". - Field descriptions for
postal_code,admin_name1,admin_code1,accuracynow say what the columns actually hold. - README.md had no counts or licence-status line; unchanged. ATTRIBUTION.txt: none in the dataset dir.
Open questions
- None blocking.
.licensing-notes.mdmay still carry dated counts; left for the pc-hfz sweep.