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 · 8.88 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-cn/

├ .licensing-notes.md

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

├ .migration-notes.md

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

├ ATTRIBUTION.txt

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

├ README.md

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

└ datapackage.yaml

https://datahub.io/logistics/postal-codes-cn/_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-cn/_r/-/datapackage.yaml

README.md— documentation

https://datahub.io/logistics/postal-codes-cn/_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-cn-sample

Field	Type	Description	Constraints	Title
country_code	string	ISO 3166-1 alpha-2 -- always CN		Country Code
postal_code	string	Chinese postal code (6 digits). Source-truncated: every code ends in '00' -- GeoNames discloses it carries only the first significant digits for China, prefecture/county-level granularity, never real 6-digit township codes.	{ "pattern": "^\\d{6}$" }	Postal Code
place_name	string	Place / county / city name		Place Name
admin_name1	string	Province-level division -- 31/34 covered (mainland only; see ATTRIBUTION.txt)		Administrative Name 1
admin_code1	string	ISO 3166-2:CN code (current alpha form, e.g. CN-BJ), verified via a name-based crosswalk		Administrative Code 1
admin_name2	string	Prefecture-level division (Shi/prefecture)		Administrative Name 2
admin_code2	string	GB/T 2260 prefecture code, truncated to 4 digits, where the source has one. Blank for the direct-administered municipalities and several prefecture-less county-level cities, where GeoNames had no real prefecture code and only an internal gazetteer ID -- blanked rather than shipped as a fake-looking code. See ATTRIBUTION.txt.		Administrative Code 2
admin_name3	string	County-level division, where the source has one		Administrative Name 3
admin_code3	string	Not populated by this source		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: 8.88 kB
Source: GeoNames postal code database -- China (CN)
License: Creative Commons Attribution 4.0 International

About this dataset

China (CN): 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.12 (closed 2026-10-02)
Commit: 321a351 (worktree commit d4eebe2, same content), landed in batch 1
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/CN.zip	The only input, as in the old builder. Mainland only, codes truncated at source to "…00"

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

Rows: 2,352 live and 2,352 fresh, none only on one side. 0 changed cells. The only class is row_order ×1: one row, 515100 Chaonan District (Guangdong, Shantou Shi), sits two rows later in the fresh file (line 2056 → 2057). Otherwise the files are identical once line endings are normalised (live CRLF, fresh LF). Consistent with GeoNames reordering its export.

Decisions

Decision	By	Basis
Accept the `row_order` difference	User (session `2479b1c9-…`, 2026-10-02: "I sign off on the row order")	Batch 1 sign-off, recorded in `docs/parity/p5.md`
Keep the "nan" → empty and "4.0" → "4" fixes even though the raw export has neither	Agent	Belt-and-braces; both defects came from the old shared pandas ingestion
Remove "2,352 postal codes", "2,349 distinct postal codes" and "79 rows" from README and descriptor; keep "31/34"	Orchestrator instruction (the README counts rule, user 2026-10-02)	Counts change whenever the data does
Leave the row counts in `ATTRIBUTION.txt` for now	User (session `2479b1c9-…`, 2026-10-02: "file a bead to fix it later")	Filed as pc-3d2, folded into pc-hfz
Drop the README's `licence_status.decision` sentence and use the standard GeoNames accuracy wording	Orchestrator (batch 1 doc fixes `b7fb93b`, then `5311ad3`), after the user said "Fix the small doc problems you've noticed"	The descriptor has no `licence_status` field

Transforms carried over

Folded from build_postal_codes_product.py (2026-09-17 audit):

admin_code1 → ISO 3166-2:CN in the current alpha form (CN-BJ, CN-AH, …) by a name crosswalk on admin_name1 over the 31 mainland divisions (Wikipedia, 2026-09-17). GeoNames' value is its own 1–33 ordinal.
admin_code2 is blanked unless it is a 4-digit GB/T 2260 prefecture code. For the direct-administered municipalities and prefecture-less county-level cities, GeoNames puts its own geonameId there.
Literal "nan" in admin_name3/admin_code3 → empty; float accuracy "4.0" → "4".
alternative_city_name is empty.
The old asserts are now ProducerErrors: row shape and country CN, 6-digit code ending in "00", known province, all 31 provinces present, unique (postal_code, place_name). The exact asserts (2,352 rows, 79 blanked) are gone.

Open questions

ATTRIBUTION.txt still says "2,352 rows", "2,271 rows" and "79 rows"; .licensing-notes.md has historical counts. Both are for pc-3d2 / pc-hfz.
The old builder's README line "For access to the full dataset… datahub@datopian.com" wasn't in the harvested README and wasn't added back. Nobody decided whether it should be.

Provenance

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