mumuy/data_location: Chinese administrative division codes as JSON

What is actually in the repository: data files, not a library

This is a data repository, and reading the top-level tree tells you what shape it takes. There is no `package.json`, no build step and no dependency manifest. What you get instead is `list.json`, `list2.json`, `list.jsonp`, a `diff.json`, a `history.json`, a `patch.txt`, a `version.js`, a `code/` directory, a `static/` directory and an `index.html` demo page. The last push was on 2026-08-27 and the project is not archived.

Two files with similar names, `list.json` and `list2.json`, sit side by side without an explanation in the README of which one a new consumer should read. The `diff.json`, `history.json` and `patch.txt` trio is the more interesting part: it suggests the dataset is maintained incrementally, with a record of what changed between versions rather than being regenerated from scratch each time.

There is a small untidiness worth noting, since it affects nothing functionally: a `.DS_Store` file is committed at the top level, which is a macOS artifact that should never have been in a repository.

The project is MIT licensed and the database itself is credited to passer-by.com, with the README directing readers there for the most complete version. The project description frames the scope as province, city, district and county, plus township and street, at three and four linked levels.

Why the two-digit code ranges matter to a consumer

The dataset is built on the national standard GB/T 2260, and the README explains how the digits are structured, because that structure is the part you can actually build logic on. Reading left to right, the first and second digits identify the province, which includes autonomous regions, municipalities directly under the central government, and special administrative regions. The third and fourth digits identify the city, covering prefecture-level cities, regions, autonomous prefectures, leagues, and the aggregation code for districts and counties under municipalities. The fifth and sixth digits identify the county, covering districts, county-level cities, and banners.

The README goes further and documents the numeric ranges, which is unusual detail for a dataset and the most useful part of the documentation. At prefecture level, ranges from XX0100 to XX2000 and from XX5100 to XX7000 indicate prefecture-level cities, while XX2100 to XX5000 indicates regions and autonomous prefectures. At county level, the README distinguishes districts and county-level cities not administered by a prefecture-level city in the XXXX01 to XXXX50 range, counties and autonomous counties in XXXX51 to XXXX80, province-administered county-level units at XX90XX, and county-level cities under a prefecture-level city in XXXX81 to XXXX99.

That level of detail means you can write validation without a lookup table. A validator that rejects a county code in the XXXX51 to XXXX80 range as a district name would be wrong, and the README is what tells you so.

Sourcing, freshness, and the gap the README admits

The README makes a strong sourcing claim for the upper three levels, saying the province, city and district data comes from the civil affairs ministry, State Council announcements and the national statistics bureau, and that it is kept timely and authoritative. Since September 2025 it adds a regulatory note: under the administrative division code management rules, division data is now published by civil affairs departments through the national place name information database. That is a change in the publishing path, and a repository tracking these codes has to follow it.

Then the README admits the weak point in plain language. Township, town and village data is described as too large to keep current, because there are many inter-level official letters involved, and the latest data is given as November 2025. So the top of the hierarchy moves with announcements while the bottom of it moves when somebody gets around to it, and those two halves sit in the same repository. The README also says the many township files are updated by overwriting files, specifically to remain compatible with old division codes.

A third boundary is drawn on purpose. The data is by administrative division, and administrative management areas overlap with divisions, so management areas are excluded: economic zones, development zones, high-tech zones, new districts and industrial parks are not collected. The README notes the exception that some management areas have been promoted to real divisions, naming Pudong New Area, Binhai New Area and Liangjiang New Area as cases where you have to tell them apart.

Getting the data into a form without a package manager

Because this is a JSON repository rather than an npm package, consuming it is a clone and a file read. There is no install command anywhere in the README, which is a fair reflection of what the project is.

git clone https://github.com/mumuy/data_location
cd data_location

The `index.html` at the root is the demo page, and the README links a live demonstration hosted at passer-by.com. Two consumption paths exist for the same data: a three-level linked selection plugin built on jQuery, and a region selection component built on Web Components. The jQuery plugin is hosted on a widget repository, and the Web Components version is offered as the forward-looking one, which is a sensible split given that the underlying data does not care which rendering approach you use.

Neither component is in this repository. What is in the repository is the dataset, so if you want the data in a form your own framework can consume, you are expected to load `list.json` yourself and map the codes to whatever component tree you already have. For that reason, treat the published files as the contract and the linked plugins as demonstrations of one way to read them.

Hong Kong, Macau and Taiwan codes are not standard codes

One caveat deserves to be read carefully if your product covers the whole country. The README states plainly that the Hong Kong, Macau and Taiwan region codes are not standard codes. They were organized by reference to the standard code rules, and they exist for user convenience so that a unified set of codes can be used.

This is the difference between a dataset that mirrors an official standard and one that extends it for usability, and it has direct consequences. Any validation you write against GB/T 2260 digit ranges will behave differently for those three regions, and any agreement with a vendor that also invented codes for them will only hold if you both copied the same invention. This repository also runs an identity card number recognition tool that depends on the same region assumptions, published separately at passer-by.com.

The README closes by inviting corrections through the repository's issue tracker, which is the mechanism to use when a code or a name is wrong. For a dataset that changes when the government publishes an announcement, that is the only update channel a consumer has.

Editorial conclusion

This repository earns its place in any product that needs a Chinese address picker without subscribing to a commercial geocoding provider, because the codes follow the national standard rather than a private taxonomy, and the files are plain JSON you can load synchronously. It is not a substitute for a geocoding service: there is no coordinate data and no place-name search, only division codes and names. Watch the two things the README itself flags, that township data was last current in November 2025 while province and city data tracks official announcements, and that the whole dataset carries the attribution of passer-by.com rather than the repository owner. Start by loading `list.json` for the three linked levels, and add the township files only when your form actually needs street granularity.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mumuy/data_location on GitHub
4. Project website
5. README