wtf is provincejson?

ProvinceJson is a data file that gives you a complete, up-to-date list of every province, city, and district in China. If you are building an app or website where users need to select their location, this ready-made dataset saves you from having to research and compile all of that administrative geography yourself. The project provides this information in JSON format, which is a structured way of organizing data that apps and websites can easily read. It covers China's three-tier administrative system: provinces at the top, cities in the middle, and districts or counties at the bottom. The maintainer has also applied a specific ordering, direct-administered municipalities like Beijing and Shanghai are listed first, provinces are ranked by GDP, and autonomous regions are placed toward the end. What makes this dataset valuable is the sheer amount of corrections and updates the maintainer has applied. China's administrative divisions change frequently through government decrees, counties become districts, cities are merged, and new areas are created. The project tracks dozens of these changes, including recent ones from 2020 and 2021 where counties were upgraded to cities or merged into districts across provinces like Jiangsu, Shandong, Guangdong, and Xinjiang. It also fills in gaps that similar datasets often miss, such as the sub-regions of Hong Kong, Macau, and Taiwan, plus special cases like island territories in Sansha. This is useful for any developer building a location picker for a Chinese audience, think of an e-commerce checkout page, a food delivery app, or a registration form that asks for a shipping address. It is essentially a curated reference file that keeps pace with how China's official boundaries evolve, so your app's location data does not go stale. The project is built on an earlier open-source dataset and refined through community contributions, with the maintainer actively encouraging users to verify their own hometown entries and report any errors.