AreaCity-JsSpider-StatsGov: CSV division data with pinyin, trimmed ids and paid town boundaries

The deliverable is CSV joined on id, with no service to call

AreaCity-JsSpider-StatsGov publishes Chinese administrative division data as CSV files rather than as a service. Two families ship in a release: ok_data_level3.csv and ok_data_level4.csv carry the division hierarchy, and ok_geo.csv carries coordinates and boundary ranges. Both tables locate a row the same way, through id, pid and deep, where deep is 0 for province, 1 for city, 2 for district and 3 for town, so a row is found by walking pid up to a deep 0 row.

Names come in pairs. The README's example for name is 武汉, the trimmed short form, while ext_name holds the full source name 武汉市, and the short form is produced by deleting province, city and district suffixes from the full one. pinyin carries the full pinyin, wu han in that same example. ext_id holds the original source number and is explicitly not unique, so it cannot stand in for id. Alongside the CSV files the repository ships browser pages for previewing the data and generating JSON or multi-level linkage js, and the scraper source that runs in the browser.

id is a stripped division code, and padding it back collides

The id field is not a key you can round trip. It is mainly the administrative division code with the 0{3,6,8,10} suffix removed, which is why ids have different lengths by level. Hong Kong, Macau and Taiwan use the older ministry numbering, rows the project added itself, such as the overseas entries, get custom numbers and carry 0 in ext_id, and when a level is missing the row is filled in from its parent with the number formed by appending 0{2} or 0{3} to the parent's ending. County level cities administered straight by a province and newly added cities are the documented examples.

The warning that matters if you join on this field is explicit: restoring the long code by padding with 00 collides with those added rows, so a 4 digit id restored to 6 digits makes some parent and child ids identical, and the added rows then need special handling. Keep the official code in your own column rather than trying to derive it from id later.

pinyin_prefix exists so sorting needs no pinyin library

Two fields exist purely to make sorting cheap. pinyin_prefix holds the first letter of the pinyin, a to z, with ~1 and ~4 used as custom prefixes for Hong Kong, Macau, Taiwan and the overseas rows the project added. pinyin holds the full pinyin, space separated. The documented sort order has two stages: sort by the first letter of pinyin_prefix, then break ties on the prefix plus the name. Implement that as written rather than sorting on the full pinyin, because the two produce different orders.

For anyone building an address selector this saves shipping a pinyin table of their own, and the ~ prefixes are the marker to filter on when domestic and added entries have to be kept apart. Nothing in the schema enforces that, so it is a convention you have to honour in your own queries.

The statistics bureau and the ministry are both struck through as sources

The data source section names six sources and strikes two of them out. The national statistics bureau's statistical division codes are gone because the data was complete but messy, updated once a year, could lag, and required development zones, economic zones, high tech zones and national new areas to be removed by hand. The bureau stopped publishing those codes in the second half of 2024. The civil affairs ministry's division codes are struck out too: they covered the first three levels and used to update monthly, but the ministry stopped publishing division code information from 2026. Both moved to the national place names database.

What is left is the place names database as the main source for township level and an auxiliary one for the first three levels, AMap as the main source for province, city and district, with its coordinates and boundaries queried whenever city data changes, and Tencent map kept for auxiliary and validation only because its data composition is described as complex. Note that the repository description still credits the bureau and the ministry: treat the data source section as current, not the description.

The April 2026 release adds Liangjiang New Area and leaves two Xinjiang counties out

The current release is tagged 2025.251231.260403 and was published on 2026-04-03, integrating place names data dated 2025-12-31, Tencent map divisions dated 2025-11-19 and AMap divisions collected on the day of the release. Its update note names three things: the place names database became a source, Chongqing abolished the Jiangbei and Yubei districts and set up the Liangjiang New Area, and the new Hekang and He'an counties in Hotan, Xinjiang are absent from this release, because the place names database has them while the AMap interface does not.

That omission is the honest limit of the dataset. When an official source runs ahead of the map APIs the project depends on, the change misses a release, and the geography has to wait for the next collection.

Township geometry is 109MB of paid, closed source data

The boundary data arrives as two very different products. ok_geo.csv.7z is 13MB compressed and more than 130MB extracted, covers province, city and district only, and is stored separately from the division files because of its size. Township boundaries are a separate download, ok_geo4_*.csv at 109MB and over 300MB once exported, labelled as paid data with advertising and closed source, with only some free sample data offered through the online preview page. The repository's MIT licence therefore covers the first three levels of geometry and no part of the fourth.

If your product needs township polygons for delivery, address validation or map rendering, budget for that separately or design around three levels. Reading the township hierarchy from ok_data_level4.csv and its coordinates from a different provider is a workable split, since the names and ids are the open part.

Boundary parsing is the hard part, and QGIS is the acceptance test

The coordinate and boundary table joins to the division table on id, and parsing it is not trivial. The repository points at src/map_geo_格式化.js for the SQL Server parsing statements and the data merge SQL, or at the AreaCity-Geo transform tool page to import the CSV into a database or convert it to shp, geojson or sql. The quality claim is specific enough to check: before each release the data is converted to shp, loaded into QGIS and imported into a database for validation, with the stated result that all shapes are valid, that parent and child and adjacent shapes keep their topology, and that there are no gaps and no overlaps.

For runtime lookups the project points at a separate repository, AreaCity-Query-Geometry, a Java program with an HTTP query interface and low memory use, credited with answering more than 10,000 coordinate lookups per second. That is a different codebase with its own release cycle, so it is a second thing to evaluate.

History gets pruned, so the README asks for a shallow clone

The repository archives its own history. Once it grows past a certain size the history is archived and large files are cleaned out of it, which loses the earlier history of some files, and older history lives in archive repositories, the one before 2023-05-28 being named AreaCity-JsSpider-StatsGov-bak-20230528. That is why both mirrors are printed with a shallow clone:

//Gitee镜像仓库: 速度快
git clone --depth 1 https://gitee.com/xiangyuecn/AreaCity-JsSpider-StatsGov.git

//源GitHub仓库: 可能比较慢或无法访问
git clone --depth 1 https://github.com/xiangyuecn/AreaCity-JsSpider-StatsGov.git

The comments name the Gitee mirror as faster and the GitHub source as possibly slow or unreachable, which also matters for the release downloads, offered through a GitHub link, a proxy link, and as a fallback the Gitee and GitHub release pages. Pruned history means the repository is a poor audit log for how a division changed, so track release tags instead. Custom data work and map development are offered through the author's QQ group rather than through the tracker.

Editorial conclusion

AreaCity-JsSpider-StatsGov is the pragmatic choice when a Chinese product needs province, city and district data with coordinates, boundaries and pinyin in one set of CSV files, and map API data is acceptable provenance for your use. It is the wrong source when you need township polygons under an open licence, when you need an audit trail of how a division changed, or when official government codes are a hard requirement rather than a convenience. Before you wire it in, check three things: that the release is recent enough for your data, that your parser handles UTF-8 with a BOM and the double quote text qualifier the README asks for, and whether the township boundary dataset is something you are willing to buy. The current release is 2025.251231.260403, published on 2026-04-03.

Frequently asked questions

Official sources

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