Hong Kong (HK) — internal licensing notes

Source research, 2026-09-17 — audit only, no build, no R2/git/datapackage.yml changes

Confirmed: Hong Kong has no operational postal code system. This is a structural fact, independently re-verified against the primary source, not inferred from the near-empty file already sitting in R2.

What was checked

• Official source — Hongkong Post itself (hongkongpost.hk/en/about_us/tips/postcode/index.html, fetched 2026-09-17): explicit statement, "postcode system is not adopted in Hong Kong", with a stated reason — the mechanized sorting system already handles mail efficiently, and a unique code down to building/street level would require up to 15 digits, judged impractical. Guidance for forms that require a postcode field: leave it blank, or fill in 000, 0000, 000000, or HKG. This is the official primary source, checked first, per this project's official-sources-before-GeoNames rule.
• Hongkong Post — general mail-services pages: no district-code or postcode-adjacent scheme found beyond the FAQ above. The recommended address format is descriptive: recipient, flat/floor, building name, street number/name, and district (per Hongkong Post's Mailing Address Format) — no numeric or alphabetic zone code is part of it.
• Hong Kong Government Address Lookup Service (ALS) — a real, separate official system exists, but it is not a postal-code system: data.gov.hk / als.gov.hk (moved from the old domain 2024-07-25) publishes a government-aggregated, building-level structured address gazetteer (English + Chinese) with 18-district codes used internally (e.g. Central and Western = C, Eastern = E, Southern = S, Wan Chai = W, Sham Shui Po = SSP, Kowloon City = KC, …). This is an address-lookup/ geocoding service, not a postcode standard, but it is a genuine, official, building-level government dataset — flagged below as a stronger candidate source than GeoNames for a future admin/locality build, consistent with the "GeoNames is fallback, not default" rule. Not fetched or evaluated for licence terms in this pass (out of scope for an audit that found no postal-code product to build against yet).
• The "999077" code: this number, which is the sole row shipped in the current R2 file (see below), is not a Hong Kong domestic postal code. It is a placeholder China Post assigns to Hong Kong for inbound/cross-border mail from mainland China; China Post does not operate inside Hong Kong, so the code is rarely used and not recognized by the public. Shipping it as "the" Hong Kong postal code without this context would mislead a customer into thinking Hong Kong has a 6-digit postcode system — it does not.
• GeoNames postal export (download.geonames.org/export/zip/HK.zip, fetched 2026-09-17): 200 OK, 1,501-byte zip, extracts to a 1-row HK.txt: HK 999077 Hong Kong Special Administrative Region 22.25 114.1667 4 (tab-delimited; no place-name detail, no admin1/2/3 fields at all). This is GeoNames' own re-export of the 999077 dummy code — confirms the current R2 file is a faithful, unmodified copy of GeoNames' postal-zip product for HK, not a broken/truncated build of something richer. GeoNames genuinely has only one row for HK.
• GeoNames main gazetteer dump (download.geonames.org/export/dump/HK.zip, fetched 2026-09-17): 200 OK, 121 KB, 2,735 total rows. Filtered to feature class P (populated places): 1,342 rows. admin1 bucket coverage among P rows: 18/18 GeoNames district buckets present (HCW, HEA, HSO, HWC = the 4 Hong Kong Island districts; KKC, KKT, KSS, KWT, KYT = the 5 Kowloon districts; NIS, NKT, NNO, NSK, NST, NTM, NTP, NTW, NYL = the 9 New Territories districts), cross-checked name-for-name against admin1CodesASCII.txt and matching Wikipedia's "Districts of Hong Kong" list exactly. 68 rows sit on GeoNames' reserved 00 bucket and 3 rows have a blank admin1 field — same shape as the ZW/SY precedent (leave blank, never guess).
• ISO 3166-2:HK: Wikipedia's ISO_3166-2:HK page (fetched 2026-09-17) confirms no ISO 3166-2 subdivision codes exist for Hong Kong at all — the article states HK "itself has no ISO 3166-2 subdivisions listed." This is a real gap versus every other admin-only/locality build in this catalogue (ZW, SY, etc. all had a real ISO 3166-2 crosswalk to build admin_code1 against). For HK, admin_code1 would have to come from GeoNames' own non-ISO bucket codes (HCW/HEA/… above) or from the government ALS district abbreviations (C/E/S/W/SSP/KC/…, which don't match GeoNames' codes either) — a genuine open design question for a future build pass, not resolved here.

Current repo state (verified, not assumed)

• datasets/hk/datapackage.yml: predates the current schema conventions used elsewhere (e.g. ZW) — it has no is_premium or data_available field, and its sources: block ("Multiple sources" / a datahub.io collections link) does not match this project's current no-sources-array-in-datapackage rule. Not corrected in this pass — audit only.
• No .licensing-notes.md existed for hk before this pass.
• The R2 "main" bucket (postal-codes, private) — fetched directly via this repo's own .env credentials, read-only:
  • hk/hk.csv — 285 bytes, Last-Modified: 2026-07-30. Content:

    country_code,postal_code,place_name,admin_name1,admin_code1,admin_name2,admin_code2,admin_name3,admin_code3,latitude,longitude,accuracy,alternative_city_name
    HK,999077,Hong Kong Special Administrative Region,nan,,nan,,nan,,22.25,114.1667,4,Babban Yankin Mulkin Hong Kong na Ƙasar Sin
    

    Bug found: admin_name1, admin_name2, and admin_name3 all contain the literal string nan, not an empty cell — a telltale pandas artifact (DataFrame.to_csv() run without na_rep='' over a column that was NaN). This is a real, if minor, data-quality defect in the shipped file, independent of the postal-code question, and was present at the file's original 2026-07-30 write (not introduced later).
  • hk/geonames/latest/0.csv and hk/geonames/2026-09-01/0.csv — same 285 bytes, same content (same nan bug), Last-Modified: 2026-09-01. These paths, and the fact that every ISO alpha-2 country prefix exists in the main bucket (ad/ through zw/, confirmed via a full top-level listing), show this is a generic monthly bulk GeoNames refresh job that runs blindly across all ~250 country codes (dated-snapshot + latest pattern, matching the US/AU/NZ "consolidated" pipelines documented in this repo's doc.md) — not a job written for or aware of Hong Kong specifically. It re-fetched GeoNames' single 999077 row again a month later and produced the same bug, unchanged.
  • _meta/catalog.json: hk is not listed as its own entry in the first 1,500 characters inspected (the file is one large array keyed by country_code); other 1-row/0-row countries (e.g. AI at 214 bytes/1 row, AF/AG at 159 bytes/0 rows) follow the exact same shape, confirming HK's near-empty file is not anomalous among countries with no real GeoNames postal coverage.
• The public/storefront copy — postal-codes-samples bucket, served at https://postal.datahub.io/hk/hk.csv (which is what datasets/hk/datapackage.yml's resource path actually points to): 276 bytes, same Last-Modified: 2026-07-30, but does not have the nan bug — admin_name1/2/3 are genuinely empty here:

  country_code,postal_code,place_name,admin_name1,admin_code1,admin_name2,admin_code2,admin_name3,admin_code3,latitude,longitude,accuracy,alternative_city_name
  HK,999077,Hong Kong Special Administrative Region,,,,,,,22.25,114.1667,4,Babban Yankin Mulkin Hong Kong na Ƙasar Sin
  

  So the two buckets have diverged: the main/private bucket's copy carries the nan defect, the public-facing storefront copy (what a customer or datahub.io visitor actually sees today) does not. Neither copy is "broken" in the sense of being truncated or malformed — both are single-row, header-plus-one-record files that faithfully reflect GeoNames' own 1-row export for HK. The near-emptiness is correct; the nan string in the private copy is a separate, minor defect.

GeoNames licence

CC BY 4.0, attribution-only, no ODbL/OSM involvement in either the postal zip export or the main gazetteer dump used for the candidate counts above — same terms already relied on for ZW/SY/BO/ET/UG/LY in this catalogue.

Free locality-directory candidate — assessment only, NOT built

Viable in principle, same shape as ZW/SY/BO/ET/UG/LY, with one open design question those precedents didn't have:

• GeoNames' main dump gives 1,342 populated places, covering 18/18 real Hong Kong districts (verified against Wikipedia's district list, not just GeoNames' own labels).
• No ISO 3166-2:HK codes exist to crosswalk against — unlike every other admin-only build in this catalogue. A future build would need to pick one of: (a) GeoNames' own non-ISO admin1 bucket codes (HCW, HEA, HSO, …), (b) the Hong Kong Government's own district abbreviations (C, E, S, W, SSP, KC, …, surfaced via ALS/data.gov.hk/CSDI), or (c) leave admin_code1 blank and carry only admin_name1. This is a genuine open decision, not a blocker — but it should be made deliberately, not defaulted, before any build starts.
• A stronger official alternative to GeoNames may exist: the Hong Kong Government's Address Lookup Service (als.gov.hk, formerly on data.gov.hk) is a building-level, bilingual, government-maintained address gazetteer with real district coding — this was not fetched or licence-checked in this pass, but per this project's GeoNames-is-fallback-not-default rule, it should be the first thing checked before defaulting to GeoNames' dump if a build is picked up.
• Whichever source is used, postal_code would be empty on every row (or the whole product could reasonably omit the 999077 dummy entry entirely, since it is not a domestic HK code and including it risks exactly the misleading impression described above) — same convention as the no-postal-code countries already shipped.

Verdict

• No-postal-code status: CONFIRMED, directly from Hongkong Post's own FAQ page (primary source, checked first), independently consistent with GeoNames' own 1-row export and every third-party summary found. This is a permanent structural fact (Hong Kong's own postal operator has stated this is a deliberate policy — mail volume and building-level addressing make a code unnecessary — not an in-progress or stalled rollout like Libya/Syria's cases). Same class as Zimbabwe/Bolivia/Curaçao/Côte d'Ivoire: permanent close-out as a postal-code product, not a "revisit later" case.
• Current 285-byte main-bucket file: CORRECT in substance (faithfully reflects that GeoNames has exactly one, non-domestic, placeholder row for HK) but carries a real, independently-confirmed data-quality bug — literal "nan" strings in three admin-name columns — that the public-facing samples-bucket copy does not have. Worth a follow-up fix pass on its own merits, separate from any locality-directory build decision.
• Free locality-directory build: VIABLE, same class as ZW/SY/BO/ET/UG/LY, pending a deliberate decision on admin_code1 sourcing (no ISO crosswalk exists here) and a look at the Hong Kong Government ALS as a possibly-better-than-GeoNames official source before defaulting to the GeoNames dump.
• Nothing was built, uploaded, or modified in this pass. datasets/hk/datapackage.yml and datasets/hk/README.md are untouched; no R2 object was written; no git change beyond this notes file.

Build, 2026-09-17 — free locality directory built, LOCAL ONLY

Following the audit above, built the free postal-code-less locality directory for Hong Kong. Local only, as instructed: no R2 upload, no git commit/push, _meta/catalog.json and datasets/hk/datapackage.yml untouched.

• Source refetched fresh: download.geonames.org/export/dump/HK.zip, 200 OK, 121,014 bytes — byte-identical size to the audit fetch above. Saved to datasets/hk/sources/HK.zip (+ extracted HK.txt, readme.txt) alongside a fresh copy of GeoNames' admin1CodesASCII.txt (datasets/hk/sources/ geonames_admin1CodesASCII.txt).
• Row counts confirmed independently: 2,735 total source rows, 1,342 feature-class-P (populated place) rows — matches the audit exactly. Admin1-bucket breakdown re-verified: all 18/18 real Hong Kong district buckets present (HCW, HEA, HSO, HWC, KKC, KKT, KSS, KWT, KYT, NIS, NKT, NNO, NSK, NST, NTM, NTP, NTW, NYL), plus 68 rows on GeoNames' reserved 00 bucket and 3 rows with a blank admin1 field — 71 unresolved rows total, shipped with blank admin_name1 rather than a guessed district.
• Decisions made explicit in the build:
  • postal_code: empty on all 1,342 rows. The old single row's 999077 (China Post's cross-border placeholder, not a real HK code) does not appear anywhere in the output — asserted in the build script.
  • admin_code1: empty on all 1,342 rows, by design — Hong Kong has no ISO 3166-2 subdivisions at all (Wikipedia's ISO_3166-2:HK article re-confirmed at build time). Disclosed in datapackage.json's field description, ATTRIBUTION.txt, and README.md, not silently left blank.
  • admin_name1: the 18 district names, taken from GeoNames' admin1CodesASCII.txt HK.* buckets and normalised to the plain display form Wikipedia's "Districts of Hong Kong" article uses (a few GeoNames labels carry a redundant "District" suffix, e.g. "Eastern District" → "Eastern", "Sham Shui Po District" → "Sham Shui Po"; the underlying GeoNames bucket code is unaffected).
  • No admin_name2/admin_code2/admin_name3/admin_code3 populated — not available at this tier from the source used.
• Files written: datasets/hk/scripts/build_postal_codes_product.py (new, modeled on datasets/ly/scripts/build_postal_codes_product.py and datasets/sy/scripts/build_postal_codes_product.py), and under datasets/hk/data/: hk.csv (1,342 rows, 69,550 bytes), hk.zip (21.4 KB), datapackage.json, README.md, ATTRIBUTION.txt. licence_status in datapackage.json: licence_id: CC-BY-4.0, decision: compatible, channel: postal-codes-r2, collected_at: 2026-09-17.
• Validated the delivered artifact, not just the in-memory build: the build script re-reads the written hk.csv back off disk and asserts row count, header shape, and that postal_code/admin_code1 are empty on every written row (not just the in-memory rows before writing). python3 -m frictionless validate datapackage.json, run from inside datasets/hk/data/ (cwd = delivery-style directory, so the relative resource path resolves the way a consumer's would): VALID.
• Spot-checked the written CSV directly: no 999077 substring anywhere in the file; no literal ,nan, sequence anywhere (the exact defect found in the shipped main-bucket R2 file above); all 18 district names present in admin_name1 with nonzero row counts (194 Yuen Long down to 6 Wan Chai), plus 71 blank-district rows.
• Old mislabeled single row: not modified or removed from R2/the storefront in this pass (out of scope per the local-only instruction) — this build produces a new, separate local artifact set under datasets/hk/data/. The existing 285-byte / 276-byte 999077 files in R2 and at postal.datahub.io/hk/hk.csv are untouched. Replacing them, updating datasets/hk/datapackage.yml, and any R2/catalog changes are explicitly out of scope here and would need a separate, approved pass.