Japan (JP) — internal licensing notes

Tier-1 official source found, 2026-09-03 — supersedes the GeoNames-only plan below

A better source than GeoNames exists and should be the primary source. Japan Post (日本郵便株式会社), the official postal operator, publishes KEN_ALL.CSV — the authoritative nationwide postal code file — at post.japanpost.jp/zipcode/dl/kogaki/zip/ken_all.zip (redirect chain verified 2026-09-03; readme at post.japanpost.jp/service/search/zipcode/download/readme.html).

Licence: explicitly better than CC BY. Verbatim from Japan Post's own readme: "郵便番号データに限っては日本郵便株式会社は著作権を主張しません。 自由に配布していただいて結構です。" ("As for postal code data specifically, Japan Post Co., Ltd. makes no copyright claim. Free distribution is permitted.") — no attribution requirement at all, stronger than GeoNames' CC-BY-4.0.

Crucially, this fixes the crosswalk hazard below at the source. KEN_ALL.CSV field 1 is the local government code under JIS X0401/X0402 — Japan's real official municipality code standard, whose first two digits ARE the real prefecture number (01=Hokkaido…47=Okinawa, the same order as ISO 3166-2:JP, because both derive from the same government numbering). Using this field directly means no alphabetical-vs-geographic crosswalk ambiguity at all — GeoNames' own reordering problem (below) simply doesn't exist if Japan Post's own code is used as the source of truth.

Trade-off, not yet resolved: KEN_ALL.CSV has no coordinates (it's address-hierarchy only: prefecture/municipality/town in kanji + katakana, plus format flags) and is Japanese-only — GeoNames would still need to be retained as a secondary join purely for latitude/longitude and any romanized names, the way SWE/ESP already blend an official admin/postal source with GeoNames for coordinates elsewhere in this catalogue. Not scoped further in this research pass — flagging the path, not building it.

GeoNames-only research, 2026-09-03 (superseded above, kept for record)

GO, but with a real crosswalk hazard flagged before any build. GeoNames' postal export has all 47 prefectures and a genuine 3-tier structure, but its own admin_code1 numbering is not ISO 3166-2:JP and must not be treated as a prependable prefix.

The source — GeoNames JP

https://download.geonames.org/export/zip/JP.zip      # 146,883 rows

Licence CC-BY-4.0, verified against export/zip/readme.txt on 2026-09-03 — Japan carries no per-country caveat (the readme's only restricted countries are GB, CL, CN, IE, MT, AR, BR).

Verified directly against the raw source file:

• admin_name1/admin_code1 — Prefecture (Todōfuken), 47/47 covered. GeoNames' own code is alphabetical-by-English-name (01=Aichi Ken, 02=Akita Ken…), NOT the real ISO 3166-2:JP north-to-south numbering (JP-01=Hokkaido, JP-13=Tokyo, JP-23=Aichi…). Verified against Wikipedia's ISO_3166-2:JP page on 2026-09-03. A build that naively prepends JP- to GeoNames' code would ship a wrong ISO code on every single row — this requires a genuine name-based crosswalk (47 rows, trivial to build once flagged, but silently wrong if missed).
• admin_name2/admin_code2 — City/Ward (Shi), 1,189 distinct values. admin_code2 is a large GeoNames-internal numeric id (e.g. 1848455), not an official Japanese administrative code (real Japanese city codes are 5-digit JIS X 0402 codes) — must be disclosed as GeoNames' own identifier, not fabricated as official.
• admin_name3 — populated on 46,523/146,883 rows (~32%) — partial town/subdivision tier, disclose as partial rather than complete.
• 436 (postal_code, place_name) collisions, verified 2026-09-03: 380 are exact full-row duplicates in GeoNames' own file (identical on every field, simple dedupe fixes them) and the remaining 56 are real border localities straddling two city wards (e.g. Kumamoto's "Nishi Ku" vs "Chuo Ku" sharing a postal code/place name) — same shape as AT's Weißenbach. Verified primary key is (postal_code, place_name, admin_code2, admin_name3): 0 collisions after dropping exact duplicates.
• Legacy corruption already visible in the currently-live bare jp.csv: literal "nan" in admin_name3, float-formatted admin_code2 ("1848455.0") — same class of fix as AT/IE/LU.

licence_status (proposed — needs a build pass before shipping)

{
  "channel": "postal-codes-r2",
  "source_url": "https://download.geonames.org/export/zip/JP.zip",
  "licence_id": "CC-BY-4.0",
  "collected_at": "2026-09-03",
  "decision": "compatible",
  "decided_by": "claude-session-2026-09-03",
  "decided_at": "2026-09-03"
}

Proposed tier

B ($49). Single source, but the prefecture ISO crosswalk is genuine research work (not a trivial prepend) and the wider primary key needs verifying — same shape as AT, more hazardous if rushed because the wrong crosswalk looks plausible (both GeoNames' code and the real ISO code are 2-digit numbers).

Verdict

Prefer Japan Post KEN_ALL.CSV as primary source, GeoNames as a coordinate-only secondary join – not pursued: post.japanpost.jp (and its CDN alias post-japanpost.durasite.net) could not be reached from this build environment (DNS resolution fails for both curl and WebFetch, despite nslookup resolving the name fine – a network-level block in this sandbox, not a licensing or research gap). Checked several GitHub mirror repos referenced in research (skitazaki/dataset-zipcode_jp, kazuhisa/ken_all, inouet/ken-all, naotsugu/jpostal) – all are code/tooling repos that fetch from Japan Post at runtime, none carry a static pre-fetched copy of KEN_ALL.CSV. This remains a known, real upgrade path for whoever can reach that domain; not something to keep retrying from this environment.

Build — 2026-09-03, GeoNames-only (Japan Post path blocked, see above)

Built via datasets/jp/scripts/build_postal_codes_product.py.

admin_code1 derived via the verified 47-entry NAME crosswalk (not a numeric prepend) – confirmed JP-01 = Hokkaido on the built output, not GeoNames' own alphabetical 01 = Aichi. admin_code2 shipped as-is but explicitly disclosed as GeoNames' internal id, not an official JIS X0402 code. Frictionless validation: valid: True. Zero literal "nan" strings, zero float-formatted accuracy, zero duplicates on the verified primary key (postal_code, place_name, admin_code2, admin_name3).

Status: built and validated locally only. Nothing published to R2, nothing committed to git yet.