echarts-china-cities-js packages city level map data for ECharts

A data package, not a library

The project collects all the geo-JSON in JavaScript of all 392 provincial level cities in 29 provinces, and acts as a static asset for jupyter-echarts or for an ECharts collection. That phrasing is the design in one sentence, because this is not a component with an API, it is a pile of files that a page can load with a script tag. The readme also states plainly that the repository is not associated with the Apache ECharts project, which is worth noting for anyone searching for an official package, because the naming and the purpose make it look like one. The two feature highlights are the shape with internal borders and the shape without them, and the shape in JavaScript and in geo-JSON form, which means the same data can be consumed by a charting library in the browser or by a Python tool that expects geo-JSON. The published package on npm is the delivery mechanism, and the project is installed the way any npm package is.

npm i echarts-china-cities-js

One file per city, named in pinyin

The directory structure in the repository is what makes the data usable. There is a js directory holding the JavaScript form, a geojson directory for the raw form, a src directory with the source data, a templates directory, a demo file and a demo page, a shape-only preview page and a shape-with-internal-borders page, and two JSON files called registry and structure that map the collection. The file names are pinyin, the romanised form of the city name, with tone numbers attached, so a file for one city is called something like a numbered syllable sequence rather than a Chinese character, and the demo page calls a helper with the city name and the id of the element to draw into. That naming convention is what lets a page reference a city without shipping the whole dataset, and it is also the thing that will trip you up, because a pinyin filename with tone numbers is not something a human reliably maps to a city name at a glance. The registry file is the answer to that, and it is worth reading before you hardcode a path.

The build is a Python pipeline feeding a gulp task

Two toolchains are involved and they do different jobs. The Python side has a script called makedemo.py and a requirements file listing pinyin, jinja2, mafan, which is a Chinese conversion library, and a CSS, HTML and JavaScript minifier. The JavaScript side has a gulpfile, and the development dependencies in the package manifest are a map maker for ECharts, a topology processing tool called mapshaper, a minifier, a directory loader and gulp itself, with the gulp plugins for minification and renaming as runtime dependencies of the build. That pairing tells the story of the pipeline. The Python script generates the demo pages and the index from templates, and the map processing tool is what turns messy source geometry into the simplified shapes a chart library can draw quickly. The test script is the only test command in the manifest and it runs nosetests, which dates the project, since that runner has been superseded for years. The repository also contains a directory for a specific fix, which is the kind of artifact a mapping data project accumulates when one region needs manual repair.

The demo pages and the preview gallery are part of the deliverable

The pages in the repository root are not decoration, they are how a user discovers what is available. There is a demo page and demo script, an index page, and two preview pages, one for shapes only and one for shapes with internal borders, and the readme shows the whole usage pattern in a single HTML file. The page loads the ECharts library, then loads one city shape file by name, then calls the helper to draw that city into a div. Everything is a script tag, so there is no bundler, no module resolution and no build step in the consuming application. The previews exist because the collection is far too large to browse from the readme, and the readme links each city in each province to an anchor in the preview page instead, which is the only practical way to expose hundreds of shapes in a markdown document. The readme also shows a section on usage with pyecharts, the Python charting library, with an example image, and the mention of jupyter-echarts as a static asset consumer covers the notebook case.

Version numbers, branches and the age of the data

The release list is short and old, with 0.0.9 in December 2017, 0.1.0 in February 2018 and 0.1.1 in March 2018, the last of them described as city optimisations, while the manifest version is now 0.1.5, so the package has been revised without new tags. The default branch is dev, and the last push was on 2026-04-23, so the work continues even though the published history stops in 2018. That gap is the thing to weigh. The map data reflects the administrative divisions as they were when it was generated, and prefecture level cities in China are reorganised periodically, so a chart built on this data can disagree with the divisions your own data uses, particularly for the municipalities and for the smaller prefectures that have been merged. The presence of the registry and structure files suggests the maintainer has thought about keeping the collection navigable, but the data age is a data age, and a project that publishes boundary data for a country whose administrative map changes should be checked against a current source before it is used in anything official. The licence is MIT and the documentation site is published on the echarts-maps GitHub Pages site, with the same pages serving as the per-city gallery.

Editorial conclusion

echarts-china-cities-js earns its place for anyone who needs a city level map of China in a browser or a notebook, because the data is already split per city and per shape style, so a chart of one province does not drag in the whole country, and because the JavaScript form can be dropped in as a static asset with no build step. It is the wrong choice for a production application that needs current administrative boundaries, since the data is a snapshot from a repository whose last release tag is from 2018 even though the branch is still touched, and it is the wrong choice if you need a different charting library. Verify three things before you rely on it: that the boundary data matches the administrative divisions your data uses, since renamings and merges of prefecture level cities happen and a chart keyed on a name can silently draw the wrong shape, which is why the package also publishes a registry and a structure file, whether you need the shape with internal borders or the outline only, since the two are separate directories and the file names differ, and how large the data is, because a page that loads every city file is a page that loads the whole country. The licence is MIT, the last push was on 2026-04-23, and the default branch is dev.

Frequently asked questions

Official sources

1. echarts-maps/echarts-china-cities-js on GitHub
2. License: MIT
3. Project website
4. README
5. Releases