# China Administrative Division Codes API (行政区划代码) (`awake_froghopper/china-administrative-divisions`) Actor

Official PRC administrative division codes (行政区划代码, MCA) for 34 provinces, 333 prefectures, 2,847 counties and 38,699 townships. Look up and validate codes, search by Chinese or pinyin, list children or export with English names. No proxy, no personal data.

- **URL**: https://apify.com/awake_froghopper/china-administrative-divisions.md
- **Developed by:** [Wayne Blomfield](https://apify.com/awake_froghopper) (community)
- **Categories:** Developer tools, AI, E-commerce
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## China Administrative Division Codes API (行政区划代码): Province, City, County, Town

**Look up, validate, search and export every official administrative division code of the People's Republic of China** (中华人民共和国行政区划代码): 34 provinces, 333 prefecture-level divisions, 2,847 county-level divisions and 38,699 township-level divisions (streets, towns, townships). Each row comes with its full parent chain, its type and an English / pinyin name.

The codes follow the Ministry of Civil Affairs (民政部) lists, the same codes used in GB/T 2260 style region codes, government forms, logistics address systems and Chinese statistics. Use it to clean address data, map Chinese region names to codes (or codes to names), build province → city → district pickers, or check whether a code is still valid after a boundary change.

- ✅ **Latest official list**, including recent changes such as the new **Liangjiang District (两江新区, 500157)** in Chongqing (2025) and **Cenling County (岑岭县, 653132)** in Xinjiang (2026)
- ✅ **4 levels**: province (省级), prefecture (地级), county (县级) and township (乡级, 9-digit codes)
- ✅ **Validation**: unknown codes come back as `not_found`, and codes abolished by an official notice come back as `abolished` with their successor and the notice URL (for example 江北区 500105 → 两江新区 500157)
- ✅ **Search in Chinese or pinyin**: `朝阳`, `chaoyang`, `tianhe`, optionally inside one province or city
- ✅ **English names and types**: `Tianhe District, Guangzhou City, Guangdong`, `Yanbian Korean Autonomous Prefecture`, `district` / `county_level_city` / `banner` / `subdistrict` / `town` …
- ✅ Accepts 2-, 4-, 6-, 9- and 12-digit codes (`44`, `4401`, `440106`, `441900003`, `440106000000`)
- ⚡ No scraping, no proxy, no external calls at run time, no personal data; a lookup finishes in about a second on 256 MB

### Who uses it

- **Cross-border e-commerce, logistics and ERP teams** normalising Chinese addresses and region fields, or mapping `province / city / district` names to codes
- **Data engineers and analysts** joining Chinese government or statistical datasets on region code (6-digit or 12-digit form)
- **App developers** who need a current China province-city-district-town list for dropdowns and cascaders
- **AI agents and MCP clients** answering *"What is the region code of Tianhe District?"* or *"Which districts belong to Guangzhou?"*

### Operations

| `operation` | Input | Output (one row each) |
|---|---|---|
| `lookup` (default) | `codes`: up to 1000 codes | one row per input code, with `status` |
| `search` | `query` (Chinese or pinyin), optional `levels`, `within`, `limit` (≤200) | matching divisions, best match first |
| `children` | `code` (empty = all provinces), optional `recursive`, `maxLevel` | sub-divisions |
| `list` | optional `levels`, `within`, `maxResults` (≤50,000) | a whole level, e.g. all counties of Guangdong |
| `stats` | none | 1 row with counts per level and type |

`levels` accepts `province`, `prefecture`, `county`, `township` (or 1–4).

### Example: look up and validate codes

Input:

```json
{ "operation": "lookup", "codes": ["440106", "500157", "500105"] }
```

Output (first row):

```json
{
  "input": "440106",
  "found": true,
  "code": "440106",
  "code12": "440106000000",
  "name": "天河区",
  "nameEn": "Tianhe District",
  "pinyin": "tian he qu",
  "level": 3,
  "levelName": "county",
  "type": "district",
  "typeEn": "District",
  "parentCode": "440100",
  "parentName": "广州市",
  "provinceCode": "440000",
  "provinceName": "广东省",
  "provinceNameEn": "Guangdong",
  "prefectureCode": "440100",
  "prefectureName": "广州市",
  "countyCode": "440106",
  "countyName": "天河区",
  "fullName": "广东省广州市天河区",
  "fullNameEn": "Tianhe District, Guangzhou City, Guangdong",
  "childCount": 21,
  "status": "active",
  "dataVersion": "2026.1",
  "path": [
    { "code": "440000", "name": "广东省", "level": 1 },
    { "code": "440100", "name": "广州市", "level": 2 },
    { "code": "440106", "name": "天河区", "level": 3 }
  ]
}
```

An abolished code:

```json
{
  "input": "500105",
  "found": false,
  "code": "500105",
  "name": "江北区",
  "status": "abolished",
  "abolished": "2025-11",
  "replacedBy": [{ "code": "500157", "name": "两江新区" }],
  "notice": "http://mzj.cq.gov.cn/zwgk_218/zfxxgkml/tzgg/202512/t20251205_15215632.html"
}
```

`status` is `active`, `abolished`, `not_found` or `invalid_format`. Bad codes never fail the run, so you can validate a whole column in one call.

### Example: search by name or pinyin

```json
{ "operation": "search", "query": "chaoyang", "levels": ["county"], "limit": 3 }
```

Returns 北京市朝阳区 `110105` (Chaoyang District, Beijing), 辽宁省朝阳市朝阳县 `211321` and 吉林省长春市朝阳区 `220104`. Add `"within": "110000"` to search only inside Beijing.

### Example: children of a city

```json
{ "operation": "children", "code": "440100" }
```

Returns the 11 districts of Guangzhou. Use `"recursive": true` with `"maxLevel": 4` to get the districts and all their streets and towns.

### Example: export all counties of a province

```json
{ "operation": "list", "levels": ["county"], "within": "440000", "maxResults": 5000 }
```

Download the dataset as JSON, CSV, Excel or XML from the run's Storage tab or the API.

### How the codes work

- **Province** `xx0000`, **prefecture** `xxxx00`, **county** `xxxxxx` (6 digits); **township** = county code + 3 digits (9 digits). Rules: MCA *Measures for the Administration of Administrative Division Codes* (民政部令第79号, 2025).
- Districts of the four municipalities (Beijing, Tianjin, Shanghai, Chongqing) and county-level cities directly under a province (e.g. 五指山市 469001, 仙桃市 429004) have the province as `parentCode`. Prefecture-level cities without counties (东莞 441900, 中山 442000, 儋州 460400, 嘉峪关 620200) have townships directly below them.
- `code12` pads the code to 12 digits for joining with NBS-style statistical codes (统计用区划代码).

### Data sources and accuracy

- Source: administrative division codes of the **Ministry of Civil Affairs of the PRC (民政部)**, published through the National Geographic Names Database (国家地名信息库, https://dmfw.mca.gov.cn/XzqhVersionPublish.html). The snapshot was assembled from two MIT-licensed open mirrors of that interface (`kk-418/cn-division`, `netnr/zoning`) and cross-checked: prefecture and county-level totals match the official MCA statistics (293 prefecture-level cities, 30 autonomous prefectures, 7 prefectures, 3 leagues; 976 districts, 398 county-level cities, 1,302 counties, 117 autonomous counties, 49 banners, 3 autonomous banners, 1 special district, 1 forestry district) once the 2025–2026 changes are applied.
- Statistical-only codes are **not** included: NBS development-zone codes (e.g. `130171`) and `市辖区` placeholder codes (e.g. `130101`) are not administrative divisions.
- Taiwan, Hong Kong and Macao appear as province-level rows only (`710000`, `810000`, `820000`), as in the MCA list.
- English names: official names for provinces; other names are Hanyu Pinyin plus an English type word, with common place-name readings fixed (Lu'an, Xi'an, Chaoyang, Bengbu…). Ethnic autonomous areas use English ethnonyms (Hui, Korean, Mongol, Tibetan…).
- The MCA publishes a full list every January (status as of 31 December) and provinces publish township changes every January and July. This Actor is updated after each release; `dataVersion` tells you which snapshot you got.
- Reference data only. For legal or official use, confirm against the latest MCA publication.

### Pricing

Pay per event:

- **Actor start**: tiny fixed fee per run
- **Result**: per row in the dataset (one per looked-up code, search hit, child or listed division)

Set a maximum charge per run and the Actor stops cleanly at the limit. Invalid input fails immediately and produces no results. Use `levels`, `within` and `maxResults` to export only what you need.

### Use from an AI agent (MCP)

One clear purpose and a typed input schema, so MCP clients can call it through the Apify MCP server. Typical prompts: *"What is the administrative code of Pudong New Area?"*, *"List all districts of Shenzhen with codes"*, *"Is 500105 still a valid Chinese region code?"*

### Related Actors

- [China Workday & Holiday Calendar API](https://apify.com/awake_froghopper/china-workday-calendar): official 调休 make-up workdays, statutory holidays, business-day arithmetic, lunar dates and solar terms

### Limits

- `lookup`: 1000 codes per run. `search`: 200 results. `children` / `list`: up to 50,000 rows (`maxResults`, default 1000).
- Mainland administrative divisions only; no postal codes, coordinates or boundaries.

### Changelog

- 0.1: first release. MCA codes for all 4 levels (status 2026), lookup / validate / search / children / list / stats, English and pinyin names, abolished-code mapping for Chongqing's 2025 reorganisation.

# Actor input Schema

## `operation` (type: `string`):

lookup = look up / validate codes (6-digit county+ codes, 9-digit township codes, 2/4-digit prefixes or 12-digit NBS-style codes); search = find divisions by Chinese name or pinyin; children = direct (or all) sub-divisions of a code; list = export a whole level, optionally inside one province/city; stats = counts per level and type.

## `codes` (type: `array`):

Administrative division codes, up to 1000 per run, e.g. 110105 (Chaoyang District, Beijing), 440106 (Tianhe District, Guangzhou), 441900003 (a township). Unknown and abolished codes come back with a status instead of failing the run.

## `query` (type: `string`):

Chinese name (朝阳, 天河区) or toneless pinyin (chaoyang, tianhe). Exact matches rank first.

## `limit` (type: `integer`):

1-200. Each returned row is one billed result.

## `code` (type: `string`):

Code whose sub-divisions you want, e.g. 440000 (Guangdong) or 440100 (Guangzhou). Leave empty for the 34 provinces.

## `recursive` (type: `boolean`):

If true, returns the whole subtree (limited by maxLevel and maxResults), not only direct children.

## `maxLevel` (type: `integer`):

1 = province, 2 = prefecture, 3 = county, 4 = township.

## `levels` (type: `array`):

Restrict to these levels: province, prefecture, county, township. Empty = all levels.

## `within` (type: `string`):

Only return divisions inside this code, e.g. 440000 for Guangdong.

## `maxResults` (type: `integer`):

Safety cap; each row is one billed result. The whole dataset is 41,913 rows.

## Actor input object example

```json
{
  "operation": "lookup",
  "codes": [
    "440106",
    "500157",
    "500105"
  ],
  "limit": 20,
  "recursive": false,
  "maxLevel": 4,
  "maxResults": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

All dataset items of the run.

## `divisions` (type: `string`):

Code, names, level, type and parent chain.

## `validation` (type: `string`):

Lookup results with found / abolished / not_found status.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "operation": "lookup",
    "codes": [
        "440106",
        "500157",
        "500105"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("awake_froghopper/china-administrative-divisions").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "operation": "lookup",
    "codes": [
        "440106",
        "500157",
        "500105",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("awake_froghopper/china-administrative-divisions").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "operation": "lookup",
  "codes": [
    "440106",
    "500157",
    "500105"
  ]
}' |
apify call awake_froghopper/china-administrative-divisions --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,awake_froghopper/china-administrative-divisions"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/YvpSDurytoIa2mcg1/builds/5IvMwXeaP6QGsgO6S/openapi.json