中国行政区划

基于国家统计局《统计用区划代码和城乡划分代码》截止 2023-06-30 版本，共 6 张表 66.5 万条数据：

层级	表名	条数	代码位数
省（自治区/直辖市）	`china_provinces`	31	2 位
地级市	`china_cities`	342	4 位
区县	`china_areas`	2,978	6 位
乡镇/街道	`china_streets`	41,352	9 位
村/居委会	`china_villages`	620,573	12 位
港澳台	`china_hk_mo_tw`	25	无代码（仅名称）

代码规则

行政区划代码采用逐级前缀：高层级代码是低层级代码的前缀。例如村代码 130111200201：

前 2 位 13 → 河北省
前 4 位 1301 → 石家庄市
前 6 位 130111 → 栾城区
前 9 位 130111200 → 南高乡
12 位 130111200201 → 南高村委会

因此任意 code 都可通过代码前缀截取直接得到所有上级 code，无需逐级回查。

注意

港澳台无标准行政区划代码，存储结构为名称，查 /hkmo 接口获取。

层级对照速查

层级英文	中文	code 长度	父级列名
`province`	省	2 位	无
`city`	地级市	4 位	`province_code`
`area`	区县	6 位	`city_code`
`street`	乡镇/街道	9 位	`area_code`
`village`	村/居委会	12 位	`street_code`

1. 获取省份列表

返回全部 31 个省级行政区。

方法: GET
路径: /api/web/china/provinces
参数: 无

响应示例

json

{
  "list": [
    { "code": "11", "name": "北京市" },
    { "code": "12", "name": "天津市" },
    { "code": "13", "name": "河北省" }
  ],
  "total": 31
}

GET在线测试

2. 按省代码获取市级列表

方法: GET
路径: /api/web/china/cities

请求参数 (Query)

参数	类型	必填	说明
`province_code`	string	是	2 位省级代码，如 `13`

请求示例

bash

GET /api/web/china/cities?province_code=13

响应示例

json

{
  "list": [
    { "code": "1301", "name": "石家庄市", "province_code": "13" },
    { "code": "1302", "name": "唐山市", "province_code": "13" }
  ],
  "total": 11
}

GET在线测试

province_code *

3. 按市代码获取区县列表

方法: GET
路径: /api/web/china/areas

请求参数 (Query)

参数	类型	必填	说明
`city_code`	string	是	4 位市级代码，如 `1301`

请求示例

bash

GET /api/web/china/areas?city_code=1301

GET在线测试

city_code *

4. 按区县代码获取乡镇/街道列表

一个区县通常有 10 ~ 30 个乡镇/街道，数据量不大但仍支持分页。

方法: GET
路径: /api/web/china/streets

请求参数 (Query)

参数	类型	必填	说明
`area_code`	string	是	6 位区县代码，如 `130111`
`page`	integer	否	页码，默认 1
`limit`	integer	否	每页条数，默认 20，最大 200

请求示例

bash

GET /api/web/china/streets?area_code=130111&limit=200

响应示例

json

{
  "list": [
    { "code": "130111200", "name": "南高乡", "area_code": "130111", "city_code": "1301", "province_code": "13" }
  ],
  "total": 8,
  "page": 1,
  "limit": 20
}

GET在线测试

area_code *

page

limit

5. 按街道代码获取村/居委会列表

一个乡镇/街道通常有 10 ~ 30 个村/居委会，部分乡镇最多上百个，支持分页。

方法: GET
路径: /api/web/china/villages

请求参数 (Query)

参数	类型	必填	说明
`street_code`	string	是	9 位乡镇/街道代码，如 `130111200`
`page`	integer	否	页码，默认 1
`limit`	integer	否	每页条数，默认 20，最大 1000

请求示例

bash

GET /api/web/china/villages?street_code=130111200

GET在线测试

street_code *

page

limit

6. 通用：按 code 获取直接下级

一个接口搞定全部级联查询：根据传入 code 的位数自动判断当前层级，返回其下一级子项。此接口最适合前端做 Cascader 级联。

方法: GET
路径: /api/web/china/children
规则:
- 省(2 位) → 返回市
- 市(4 位) → 返回区县
- 区(6 位) → 返回乡镇/街道
- 街道(9 位) → 返回村/居委会
- 村居(12 位) → 返回错误（已是最低层级）

请求参数 (Query)

参数	类型	必填	说明
`code`	string	是	2/4/6/9 位行政区划代码
`page`	integer	否	页码（仅街/村生效）
`limit`	integer	否	每页条数（仅街/村生效）

请求示例

bash

# 查广东省（44）下级 → 21 个地级市
GET /api/web/china/children?code=44

# 查广州市（4401）下级 → 11 个区
GET /api/web/china/children?code=4401

# 查天河区（440106）下级 → 街道
GET /api/web/china/children?code=440106

响应示例（code=4401）

json

{
  "list": [
    { "code": "440103", "name": "荔湾区", "city_code": "4401", "province_code": "44" },
    { "code": "440104", "name": "越秀区", "city_code": "4401", "province_code": "44" }
  ],
  "level": "area",
  "total": 11
}

GET在线测试

code *

page

limit

7. 按 code 查询详情 + 完整路径

返回指定代码的自身详情以及从省到本级的完整路径。

方法: GET
路径: /api/web/china/detail

请求参数 (Query)

参数	类型	必填	说明
`code`	string	是	2/4/6/9/12 位任意层级代码

请求示例

bash

GET /api/web/china/detail?code=130111200201

响应示例

json

{
  "level": "village",
  "current": {
    "code": "130111200201",
    "name": "南高村委会",
    "street_code": "130111200",
    "area_code": "130111",
    "city_code": "1301",
    "province_code": "13"
  },
  "path": [
    { "level": "province", "code": "13", "name": "河北省" },
    { "level": "city",     "code": "1301", "name": "石家庄市" },
    { "level": "area",     "code": "130111", "name": "栾城区" },
    { "level": "street",   "code": "130111200", "name": "南高乡" },
    { "level": "village",  "code": "130111200201", "name": "南高村委会" }
  ],
  "full_name": "河北省 / 石家庄市 / 栾城区 / 南高乡 / 南高村委会"
}

GET在线测试

code *

8. 按名称或代码前缀搜索

名称模糊搜索（LIKE %keyword%），若 keyword 为纯数字还会自动加 code 前缀匹配。

方法: GET
路径: /api/web/china/search

请求参数 (Query)

参数	类型	必填	说明
`keyword`	string	是	关键词（1-50 字）
`level`	string	否	限定层级：`province`/`city`/`area`/`street`/`village`，默认全层级
`limit`	integer	否	返回条数，默认 20，最大 50

请求示例

bash

# 名称模糊搜索
GET /api/web/china/search?keyword=天河

# 仅搜索区县级
GET /api/web/china/search?keyword=长安&level=area

# 代码前缀搜索（keyword 为纯数字自动匹配 code 前缀）
GET /api/web/china/search?keyword=440106

响应示例（keyword=天河）

json

{
  "keyword": "天河",
  "list": [
    {
      "level": "area",
      "code": "440106",
      "name": "天河区",
      "province_code": "44",
      "city_code": "4401",
      "area_code": null,
      "street_code": null
    }
  ],
  "total": 1
}

搜索性能

搜索是按 province → city → area → street → village 顺序逐级查询，一旦达到 limit 就停止后续查询，避免遍历 62 万村数据。

GET在线测试

keyword *

level

limit

9. 港澳台行政区划

港澳台数据无行政区划代码，按「省级 → 次级区域 → 区/乡镇」三层名称存储。

方法: GET
路径: /api/web/china/hkmo

请求参数 (Query)

参数	类型	必填	说明
`region`	string	否	限定省级，如 `香港特别行政区` / `澳门特别行政区` / `台湾省`

请求示例

bash

# 全量
GET /api/web/china/hkmo

# 仅香港
GET /api/web/china/hkmo?region=香港特别行政区

响应示例

json

{
  "list": [
    {
      "id": 1,
      "region": "香港特别行政区",
      "sub_region": "香港岛",
      "areas": ["中西区", "湾仔区", "东区", "南区"]
    },
    {
      "id": 2,
      "region": "香港特别行政区",
      "sub_region": "九龙",
      "areas": ["油尖旺区", "深水埗区", "..."]
    }
  ],
  "total": 25
}

GET在线测试

region

10. 省-市-区三级联动树

一次性返回嵌套 children 结构的完整联动树，适合前端级联选择器组件。

方法: GET
路径: /api/web/china/tree

请求参数 (Query)

参数	类型	必填	说明
`province_code`	string	否	2 位省代码，空=返回全部省（31 省 + 下属全部数据，数据量较大）
`with_streets`	integer	否	是否把街道也返回（共 4 层），可选 `0`或`1`，默认 `0`（只返回 3 层：省-市-区）

请求示例

bash

# 仅广东省（44）+ 下属市/区（三级树）
GET /api/web/china/tree?province_code=44

# 北京市 + 市/区/街道（四级树）
GET /api/web/china/tree?province_code=11&with_streets=1

# 全中国省-市-区三级联动树
GET /api/web/china/tree

响应示例（省=44 省=广东节选）

json

{
  "tree": [
    {
      "code": "44",
      "name": "广东省",
      "children": [
        {
          "code": "4401",
          "name": "广州市",
          "children": [
            { "code": "440103", "name": "荔湾区", "children": [] },
            { "code": "440104", "name": "越秀区", "children": [] },
            { "code": "440106", "name": "天河区", "children": [] }
          ]
        }
      ]
    }
  ],
  "total": 1,
  "with_streets": 0,
  "level": 3
}

性能提示

/tree（空参数）= 全中国省-市-区共 3351 条数据，响应约 100KB，可直接加载
/tree?with_streets=1（空参数）= 4.4 万条数据，响应约 1MB，建议缓存或限定 province_code

GET在线测试

province_code

with_streets

通用说明

统一响应格式

所有接口响应均由 formatDatas 统一包装：

json

{
  "code": 200,
  "data": { ... },
  "message": "success"
}

分页说明

/streets、/villages 以及 /children 查街道/村时返回 {list, total, page, limit} 分页结构
其他小数据量接口仅返回 {list, total}，可直接全量渲染

中国行政区划 ​

层级对照速查 ​

1. 获取省份列表 ​

响应示例 ​

2. 按省代码获取市级列表 ​

请求参数 (Query) ​

请求示例 ​

响应示例 ​

3. 按市代码获取区县列表 ​

请求参数 (Query) ​

请求示例 ​

4. 按区县代码获取乡镇/街道列表 ​

请求参数 (Query) ​

请求示例 ​

响应示例 ​

5. 按街道代码获取村/居委会列表 ​

请求参数 (Query) ​

请求示例 ​

6. 通用：按 code 获取直接下级 ​

请求参数 (Query) ​

请求示例 ​

响应示例（code=4401） ​

7. 按 code 查询详情 + 完整路径 ​

请求参数 (Query) ​

请求示例 ​

响应示例 ​

8. 按名称或代码前缀搜索 ​

请求参数 (Query) ​

请求示例 ​

响应示例（keyword=天河） ​

9. 港澳台行政区划 ​

请求参数 (Query) ​

请求示例 ​

响应示例 ​

10. 省-市-区三级联动树 ​

请求参数 (Query) ​

请求示例 ​

响应示例（省=44 省=广东节选） ​

通用说明 ​

中国行政区划

层级对照速查

1. 获取省份列表

响应示例

2. 按省代码获取市级列表

请求参数 (Query)

请求示例

响应示例

3. 按市代码获取区县列表

请求参数 (Query)

请求示例

4. 按区县代码获取乡镇/街道列表

请求参数 (Query)

请求示例

响应示例

5. 按街道代码获取村/居委会列表

请求参数 (Query)

请求示例

6. 通用：按 code 获取直接下级

请求参数 (Query)

请求示例

响应示例（code=4401）

7. 按 code 查询详情 + 完整路径

请求参数 (Query)

请求示例

响应示例

8. 按名称或代码前缀搜索

请求参数 (Query)

请求示例

响应示例（keyword=天河）

9. 港澳台行政区划

请求参数 (Query)

请求示例

响应示例

10. 省-市-区三级联动树

请求参数 (Query)

请求示例

响应示例（省=44 省=广东节选）

通用说明