Part of a Data Solution

Postal Codes Solution
Every worldwide postal-code dataset in one bundle — the ultimate global reference for precise postal codes.
Explore →

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

20% off

$49.90$39.92

one-time payment

Download sample · CSV · 9.91 kB Report an Issue

API Access

Access dataset files directly from scripts, code, or AI agents.

Browse dataset files

Dataset Files

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.

/logistics/postal-codes-jp/

├ .licensing-notes.md

https://datahub.io/logistics/postal-codes-jp/_r/-/.licensing-notes.md

├ .migration-notes.md

https://datahub.io/logistics/postal-codes-jp/_r/-/.migration-notes.md

├ ATTRIBUTION.txt

https://datahub.io/logistics/postal-codes-jp/_r/-/ATTRIBUTION.txt

├ README.md

https://datahub.io/logistics/postal-codes-jp/_r/-/README.md

└ datapackage.yaml

https://datahub.io/logistics/postal-codes-jp/_r/-/datapackage.yaml

Key Files

Start with these files — they give you everything you need to understand and access the dataset.

datapackage.yaml— metadata & schema

https://datahub.io/logistics/postal-codes-jp/_r/-/datapackage.yaml

README.md— documentation

https://datahub.io/logistics/postal-codes-jp/_r/-/README.md

Typical Usage

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-jp-sample

Field	Type	Description	Constraints	Title
country_code	string	ISO 3166-1 alpha-2 -- always JP		Country Code
postal_code	string	Japanese postal code (7 digits, NNN-NNNN)	{ "pattern": "^\\d{3}-\\d{4}$" }	Postal Code
place_name	string	Locality/town name		Place Name
admin_name1	string	Prefecture (Todofuken) -- 47/47 covered		Administrative Name 1
admin_code1	string	ISO 3166-2:JP code		Administrative Code 1
admin_name2	string	City/Ward (Shi)		Administrative Name 2
admin_code2	string	GeoNames' own internal numeric id -- NOT an official Japanese administrative code (real municipality codes are 5-digit JIS X0402, not carried by this source)		Administrative Code 2
admin_name3	string	Town/subdivision -- partial coverage (empty where GeoNames gives none)		Administrative Name 3
admin_code3	string	GeoNames' 5-digit code for the ward in admin_name3 (the JIS X0402 local-government code, e.g. 01102 for Sapporo Kita Ku); empty where GeoNames gives none		Administrative Code 3
latitude	number	GeoNames latitude (WGS84)		Latitude
longitude	number	GeoNames 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	Not populated in this release		Alternative City Name

Download

Download sample CSV

About

Last updated: 2 October 2026
Total rows: 100
Format: CSV
File size: 9.91 kB
Source: GeoNames postal code database -- Japan (JP)
License: Creative Commons Attribution 4.0 International

About this dataset

Japan (JP): 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.29 (closed 2026-10-02)
Commit: a8c36ac (worktree commit b9bb883, identical diff), landed in batch 2; accuracy wording later changed in 5311ad3
Parity verdict: explained (row_order only); signed off by the user
Producer: custom, refresh disabled

Sources

Input	URL	Notes
GeoNames postal export	https://download.geonames.org/export/zip/JP.zip	The only input the old builder used

Japan Post's KEN_ALL.CSV is the stronger official source, but it could not be reached from the original build environment (per the produce.py docstring and .licensing-notes.md, 2026-09-03). Not pursued in P5.

Parity against the live zip (2026-10-02)

Rows: 146,503 live and 146,503 fresh, none only on one side, 0 changed cells. One class, row_order. Live is CRLF, fresh is LF. The informational sample check was format-only.

Cause: GeoNames reordered its export. Rows with the same postal_code and place_name but different wards come out in the other order; the stable sort keeps source order among ties. Examples:

950-0101 Eguchi: live has Konan Ku (15104) before Higashi Ku (15102); fresh has the reverse.
950-0102 Hosoyama: Kita Ku / Konan Ku swapped the same way.

Decisions

Decision	By	Basis
Accept `row_order`	User, 2026-10-02 ("agree to all", session 2479b1c9)	Batch 2 sign-off in `docs/parity/p5.md`
Describe `admin_code3` as GeoNames' 5-digit ward code (the JIS X0402 local-government code, e.g. 01102 Sapporo Kita Ku) instead of "Not populated"	Agent proposed; user approved 2026-10-02 ("agree to all", session 2479b1c9)	Live and fresh both carry these codes. The JIS X0402 label is the agent's identification from the codes; the orchestrator checked 01102 fits the scheme
Remove "1181 distinct values" from `admin_name2`	Agent; orchestrator kept it	A count from the data, not a fixed set of admin units. Reported to the user, who replied "agree to all"
Remove row, distinct-code, admin3-fill and duplicate counts from README and descriptor; drop the stale `licence_status` sentence; standard accuracy description	Orchestrator instruction (P5 brief)
Accuracy description says GeoNames documents 1/4/6 and other values (e.g. 3) occur upstream	Orchestrator (`5311ad3`, all batch-2 descriptors)	Reported to the user with batch 2; "agree to all"

Transforms carried over

From build_postal_codes_product.py:

admin_code1 → ISO 3166-2:JP by a name crosswalk of the 47 prefectures. GeoNames' own code is alphabetical (01 = Aichi Ken), so prefixing it would be wrong on every row.
Exact full-row duplicates dropped, first kept (the old builder recorded 380, found byte-identical in 2026-09-03 research).
Stable sort by (admin_code1, postal_code, place_name), so the file runs north to south.
alternative_city_name empty. Everything else verbatim, including GeoNames' stray spaces ("Sapporo Shi ", " Kita Ku"). admin_code2 is GeoNames' internal id.
The old asserts are ProducerErrors: known prefecture, NNN-NNNN postal code, no literal "nan", no float accuracy, unique (postal_code, place_name, admin_code2, admin_name3), all 47 prefectures present. No row-count assert.
build_postal_codes_product.py and publish_r2.py removed.

Open questions

ATTRIBUTION.txt ("146,503 rows", the 46,265 admin_name3 fill count) and .licensing-notes.md still carry counts; left for the end-of-epic sweep (pc-hfz, which subsumes pc-3d2).

Provenance

Reconstructed 2026-10-05 from the agent transcript 2479b1c9-c4dd-47e5-be82-34ccf8d49a80/subagents/agent-a6ea04a5f5e0b2059.jsonl, the orchestrator session 2479b1c9-…, the commit messages (a8c36ac, 5311ad3), the bd close reason and docs/parity/p5.md.