province-city-china: China's GB/T 2260 administrative division codes as JSON, CSV and SQL

The problem province-city-china solves, and who actually has it

Address forms, logistics routing, tax registration and analytics dashboards all need the same thing: the official hierarchy of Chinese administrative divisions, keyed by the GB/T 2260 code. That hierarchy is four levels deep (province, city, county, town) and it changes. Counties get upgraded to cities, districts get merged, and a code that was valid in one year may be retired the next. Teams that hardcode a list of a few hundred city names eventually discover their dropdown no longer matches what the courier company or the tax bureau expects.

This repository exists to hand you that list as files instead of an API. The package.json describes it as an util to query china province, city and district data, and names the standard it follows: GB/T 2260. The audience is narrow and specific. You are building something that must present Chinese administrative divisions to a user or validate them on input, and you would rather not run another service to do it. A checkout form with a province and city selector, an internal CRM with a district field, a data warehouse that needs to join a free-text address to a region code. If your product has no Chinese address surface, this repository has nothing for you.

How the data pipeline works: scrape, check, generate, copy

The repository is a Lerna monorepo. Its root package.json is private and declares workspaces under packages/*, so the published artifacts live in sub-packages while the root holds the build orchestration. The start script chains the whole pipeline in a fixed order, and the script names double as documentation of the data flow.

The first step, get, pulls province, city and district data. The second, hongkong, pulls district-level data for Hong Kong and Macau separately, which is a signal that those two regions are not sourced from the same place as the mainland divisions. The third, check, validates the district data before anything downstream consumes it. The fourth, get:town, fetches the town and street level, the deepest layer. The fifth, sql, generates both SQL and a province-city-district data.json. The sixth, level, regenerates the hierarchical level data. The seventh, code, fetches long-distance telephone area codes. The eighth, copy, distributes the generated files into the individual packages.

That ordering matters if you ever want to rebuild the dataset yourself. Each stage feeds the next, and the check stage sits between the fetch and the generation steps rather than at the end, so bad district records are caught before they propagate into the SQL and the hierarchical files. The root also defines a version script that runs lerna version with --exact --force-publish --no-push --no-git-tag-version, which tells you releases are cut as a lockstep version bump across all workspace packages rather than independently per package.

Installing province-city-china and reading your first division

The repository is a data package, so installation is the ordinary npm route. The README does not spell out a single canonical install command in the excerpt available, but the root package.json and the workspace layout make the shape clear: the queryable artifact is published from the packages directory as province-city-china. The root scripts reach it through yarn workspace province-city-china, which is the same package name a consumer would install.

yarn workspace province-city-china get

That is the first stage of the root start script, the one that pulls province, city and district data. Running it is how the maintainers refresh the dataset, and reading the script list is how you find out which stage produces which file. The generation steps write their output into the package's dist directory, so the first thing worth doing after install is looking at the package contents to see which levels and formats shipped in the version you pinned.

yarn workspace province-city-china sql

That is the fifth stage, the one the root package.json labels as generating SQL and the province-city-district data.json. Expect JSON files for the division levels and the SQL dump generated by that step. Because the repository ships several representations of the same hierarchy, the practical first use is to load the JSON for the level you need and filter it by parent code rather than to reach for a query layer. For a province selector you read the top level array; for a city selector you filter by the province code you already hold. The telephone area code data produced by the code step is a separate file, so if your form needs an area code next to the city, check that the file exists in the package before designing around it. The project's homepage at uiwjs.github.io/province-city-china is the place the README points to for browsing the data.

Where the file-based approach breaks down

The most important limitation is that this is a snapshot, not a feed. The README describes a pipeline that fetches and regenerates data; nothing in the repository layout suggests a scheduled job that runs it for you. Releases are infrequent: v8.5.6 in October 2022, v8.5.7 in November 2023, v8.5.8 in September 2024. The last push to the default branch was on 2026-04-21, which is recent, but a push is not the same as a published data refresh, and the release history shows the gap between the two can be long. If your application must reflect an administrative change the month it is announced, you are responsible for rebuilding from the pipeline or waiting for a release.

The second limitation is scope. The dataset covers administrative divisions and, per the pipeline, telephone area codes. It does not carry postal codes, geographic boundaries, coordinates or population figures. Anything that needs a polygon on a map, a distance calculation or a demographic join is outside what these files contain, and no amount of filtering will produce it.

The third is the shape of the hierarchy itself. Hong Kong and Macau are fetched by a separate script step from the mainland divisions, and the town level is fetched by yet another. If you assume a uniform four-level tree across every region, you will find that the top of the tree is assembled from more than one source with more than one structure. Validate against your own data before you trust a parent-child join across all regions.

Compared with querying a live administrative division API

The obvious alternative is a hosted API that returns administrative divisions on demand. The difference is not accuracy, it is where the staleness lives. With an API, the provider owns the refresh cycle and you own a network dependency: every address form submission becomes a request, and an outage in the provider becomes an outage in your form. With province-city-china, the refresh cycle is a release you have to notice, and the dependency is a version number in your lockfile. You trade an operational dependency for a maintenance one.

A second alternative is generating the data yourself from the National Bureau of Statistics published codes. That is effectively what this repository's pipeline does, and the root package.json gives you the script sequence to imitate: get, hongkong, check, get:town, sql, level, code, copy. Doing it yourself buys you control over the fetch sources and the cadence. It also buys you the check stage, the Hong Kong and Macau special case, the telephone area code fetch, and the distribution step into multiple packages, all of which you would have to write and keep working. For most teams the repository is the cheaper path; for a team that already ingests official statistics, it is a duplicate.

Licence, versioning and the cost of staying current

The licence is MIT, declared in the root package.json and shipped as a LICENSE file at the top level. MIT is permissive: you can use the data in commercial and closed-source products, and you keep the copyright notice. The repository also carries a sponsorship section in its README with links to the author's macOS applications, which is a funding mechanism rather than a licence term, so it does not change your obligations. Nothing here is legal advice; read the LICENSE file yourself before shipping.

The upgrade cost is the part teams underestimate. Because the root version script runs lerna version with --force-publish, the workspace packages move together, so a data refresh arrives as a version bump on the package you installed rather than as a separate data release you can pull alone. That means upgrading is a dependency change, and any code that assumed a particular division code or a particular file name in the package needs to be re-checked against the new output. Pin the version, and treat a bump as a data migration with a review step rather than as a routine patch.

Editorial conclusion

Adopt it if you need a static, MIT-licensed copy of China's four-level administrative division codes in JSON, CSV or SQL and can pin a version and re-pull when the National Bureau of Statistics publishes new codes. Do not adopt it if you need live boundary geometry, postal codes, or a maintained API with a support commitment, because the repository ships files, not a service. Before wiring it in, open packages/province-city-china/dist and check that the levels and the telephone area codes you need are actually present, then decide whether you consume the npm package or vendor the JSON directly into your own build.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. uiwjs/province-city-china on GitHub