AreaCity-JsSpider-StatsGov: Chinese province, city, district and township data with pinyin, coordinates and boundaries

What AreaCity-JsSpider-StatsGov actually ships

The repository is a data distribution with tooling around it, not a runtime library you import. Its README describes three CSV products. ok_data_level3.csv and ok_data_level4.csv arrive together in a 7z archive and hold three level (province, city, district) and four level (province, city, district, township) administrative divisions. ok_geo.csv.7z holds coordinates and boundaries for the three level set and unpacks to over 130 MB. A fourth file family, ok_geo4_*.csv, holds township level coordinates and boundaries, and the README marks it as paid, advertising supported and closed source, with only partial free data for testing.

The audience is narrow and specific: developers building address pickers, delivery zone checks, map drilldowns or regional statistics for mainland China. The name is misleading. The JavaScript spider in src/ is the extraction source that produced the data, and it runs in a browser, but you are not expected to run it. You are expected to download the CSV.

How the four level hierarchy is encoded in the CSV

The division table is a flat adjacency list. Each row carries id, pid, deep, name, pinyin_prefix, pinyin, ext_id and ext_name. deep is 0 for province, 1 for city, 2 for district and 3 for township. pid points at the parent id, so building a cascading selector is a matter of filtering by pid at each step rather than parsing a nested structure.

The id field deserves attention. The README states it is mainly the administrative division code with trailing 0{3,6,8,10} suffixes stripped, producing a short number. Hong Kong, Macau and Taiwan keep older Ministry of Civil Affairs codes, and added entries such as foreign regions get custom IDs. When a level is missing, for example a county level city administered directly by a province, the row is filled from the parent and the ID is the parent's with 0{2,3} appended. The README warns directly that restoring long codes by appending zeros will collide with these synthesized IDs. If your system keys on official codes, do not treat id as one; use ext_id, which the README notes is not unique and can equal the parent's value for filled rows.

Names are split in two. name is the shortened form, and ext_name is the full source name. The README gives 武汉 for name and 武汉市 for ext_name, and states that name is exactly the first part of ext_name. pinyin holds the full pinyin with spaces, while pinyin_prefix is the first letter or a custom prefix such as ~1 or ~4 for Hong Kong, Macau, Taiwan and foreign entries. Sorting by pinyin_prefix first and then by prefix plus name is the ordering the README prescribes.

Downloading the data and generating a cascading selector

There is no package to install. The README points at GitHub Releases and a Gitee mirror, and notes that if both download routes fail you can pull the repository itself. Because history in the repository grows large, the README recommends a shallow clone.

git clone --depth 1 https://gitee.com/xiangyuecn/AreaCity-JsSpider-StatsGov.git

The Gitee mirror is presented as the faster route; the GitHub URL is the source repository and the README warns it may be slow or unreachable. Either way you get the source tree, not the release archive, so the CSV files still come from Releases.

After unpacking ok_data_level3-4.csv.7z, the README states the CSV is utf-8 with a BOM and uses " as the text qualifier. Parsing it with a library that expects plain utf-8 and no BOM is the most common way to get garbled first-column values. If you would rather not write the cascade yourself, the README describes an online preview page that generates JSON and multi-level linked JavaScript from the same data, and a separate conversion tool page for importing the CSV into a database or exporting sql, shp and geojson. Both run from the project's github.io deployment, and the README says you can download the repository and open the HTML files locally if that deployment is unreachable.

Where the dataset stops being free, and where it is already stale

The boundary data is split by licence and price in a way the division data is not. ok_geo.csv.7z covers province, city and district boundaries and is part of the open distribution. The township boundary files are described as paid, advertising supported and closed source, with only partial free samples. If your use case needs township polygons, this repository is the wrong tool at the open tier, and the README does not document what the paid tier costs or what its redistribution terms are.

Currency is the second constraint. The 2026-04-03 release notes state that the update does not include 和康县 and 和安县, two newly established counties in Hotan, Xinjiang, because the national place name database had them but the Amap interface did not. The same notes record that Chongqing abolished Jiangbei and Yubei districts and established Liangjiang New Area. So the release is current on one change and explicitly behind on another, and the gap is caused by a data source, not by the maintainer. Any address validation that must match a government register exactly will need a manual patch for cases like this.

A third limitation is structural. The README explains that the Ministry of Civil Affairs stopped publishing administrative division codes in 2026 and the National Bureau of Statistics stopped publishing statistical division codes in the second half of 2024, so the project shifted to the national place name database. That means the upstream chain now depends on a single primary source for township level data, with Tencent and Amap used for verification and for coordinates and boundaries.

AreaCity-Query-Geometry and the conversion toolchain

Two companion pieces matter if you plan to do more than display a dropdown. The AreaCity-Geo format conversion tool imports the division, coordinate and boundary CSVs into a database and exports sql, shp and geojson, and it can convert coordinate systems. The README points anyone exporting boundaries to geojson at AreaCity-Query-Geometry, a separate Java open source program with an HTTP query interface that the README says can look up the city information for more than 10,000 coordinates per second with low memory use. That figure is the project's own claim, not an independent measurement.

Compared with pulling boundaries from Amap or Tencent directly, the difference in approach is that this project freezes a snapshot into files you own. You get reproducible inputs and no API quota, at the cost of doing your own refresh. Against something like Alibaba Cloud DataV GeoAtlas, which also publishes Chinese boundary geojson, the distinction is scope: this project carries four levels with pinyin and a documented field schema, while a boundary atlas is primarily polygons. If all you need is a province outline for a chart, the heavier dataset here is overkill.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-04-03, which is over five months before this article's frame of reference. Treat it as a project that publishes on its own cadence rather than one with continuous commits. The release history supports that reading: 2025.251231.260403 on 2026-04-03, 2023.240319.250114 on 2025-01-14, and 2023.240319.240616 on 2024-06-16. Roughly annual releases, with the latest one adding the national place name database as a source.

Upgrading is not a package bump. You re-download the CSV, re-import it, and reconcile any IDs that changed because a division was created, merged or abolished. The README's own note about Chongqing and the two missing Xinjiang counties is exactly the kind of change that will surface as a diff in your data. Budget for a reconciliation step, not just a file replacement.

The licence is MIT. That covers the code in the repository, and the README presents the division and three level boundary CSVs as part of the same open distribution. The township boundary tier is described as paid and closed, so it sits outside that grant. The README does not spell out the licence of the underlying source data from the national place name database, Tencent or Amap, and this article cannot resolve that; check with your own legal counsel before redistributing the CSVs as a product.

The extraction source in src/

The repository includes browser runnable JavaScript extraction source, and the project name reflects it. The README lists the data sources the extraction covers: the national place name database for four level data, Tencent's administrative region web service for four level data used for verification, and Amap's district API for the first three levels, plus Amap for coordinates and boundaries when a city changes. The README states that Amap is the primary source and updates frequently but at unknown times, and that Tencent's current data composition is complex so it is used only as an auxiliary and validation source.

For most readers the spider is provenance rather than a tool. Running it yourself means reimplementing the merge logic the maintainer applies across three sources, including the rules for which source wins. The README does not document those merge rules, so the extraction source is best treated as an audit trail for how a release was assembled, not as a supported pipeline you can operate.

Editorial conclusion

Adopt it if you need Chinese administrative divisions with pinyin and stable short IDs, and if province, city and district level is enough for your product. Do not adopt it if you need township level boundary polygons under a permissive licence, because that tier is paid, closed and advertised; the free ok_geo.csv stops at district level. Before building on it, verify the CSV encoding (utf-8 with BOM, quote character ") against your own parser, confirm that the id field is a shortened code rather than a raw administrative code, and check the release notes for the specific update you are pulling, since the 2026-04-03 release explicitly omits two newly created counties in Xinjiang.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xiangyuecn/AreaCity-JsSpider-StatsGov on GitHub