中国行政区划数据 · 开放 API 文档

接入说明

全部 GET

接口地址

https://open.suujee.com/region/api.php

请求方式

GET，参数走 query string

响应格式

{"ok":true,"data":…} 或 {"ok":false,"error":"…"}

鉴权

必需。请求头 X-API-Key: pk_xxxxxxxx（推荐）或参数 ?api_key=pk_xxxxxxxx；所有 act 都要携带，缺少或错误返回 401

密钥获取

在用户中心 → API 密钥中手动生成。密钥为平台级、站内所有应用通用；明文仅在生成时展示一次，服务端只存 bcrypt 哈希

限流

按每个密钥滑动窗口限流：120 次 / 60 秒，超限返回 429。参考数据变动极慢，建议调用方自行缓存以节省额度

跨域

已开启 CORS（Access-Control-Allow-Origin: *），支持 OPTIONS 预检，允许头 X-API-Key

状态码

200 成功 · 400 参数错误 · 401 未授权 · 404 未找到 · 429 限流 · 500 内部异常 · 503 数据未就绪。
注意：出错时 HTTP 状态码不再是 200，但响应体仍是上面的 JSON 信封，可只按 ok 字段判断

调用示例（下方各 act 的示例都需携带 X-API-Key）：

curl -H "X-API-Key: pk_xxxxxxxx" \
  "https://open.suujee.com/region/api.php?act=parse&q=河北省无极县七汲镇"

① 地址解析

act=parse

参数	必填	说明
q	是	待解析的地址文本

GET api.php?act=parse&q=河北省无极县七汲镇

{
  "ok": true,
  "data": {
    "ok": true,
    "input": "河北省无极县七汲镇",
    "levels": {                          // 键是层级 1省 2地 3县 4乡；本地址省略了地级，故没有 "2"
      "1": {"id":"630","code":"130000000","name":"河北省","level":"1","type":"省","full_path":"全国/河北省"},
      "3": {"id":"826","code":"130130000","name":"无极县","level":"3","type":"县","full_path":"全国/河北省/石家庄市/无极县"},
      "4": {"id":"828","code":"130130101","name":"七汲镇","level":"4","type":"镇","full_path":"全国/河北省/石家庄市/无极县/七汲镇"}
    },
    "province": {…}, "city": null, "county": {…}, "town": {…},
    "resolved": {                        // 已按继承规则解析
      "postcode":"052460", "areacode":"0311", "plates":"冀A",
      "urban_cat":"220", "urban_name":"村庄", "urban_ratio":"0.2500",
      "full_path":"全国/河北省/石家庄市/无极县/七汲镇"
    },
    "ambiguous": null,
    "rest": "",
    "std": "河北省无极县七汲镇"
  }
}

注意：id / level / urban_ratio 这类数值字段实际以 字符串返回（数据库驱动行为），比较或计算前请先转换。

省略层级是允许的。「河北省无极县七汲镇」没有写石家庄市（无极县是石家庄市下辖的县），接口会自动跨过被省略的层级 —— 返回的 levels 里就没有 "2"。
同名歧义（如「长安区」在石家庄与西安各有一个）返回 ambiguous.candidates 候选列表（含 full_path 供区分），此时 levels 为空。

② 取下级

act=children

参数	必填	说明
id	二选一	节点 id（来自 detail / children）
code	二选一	9 位行政区划代码，如 `370000000`

GET api.php?act=children&code=370000000

返回该节点的**直接下级**（含开发区等补充单位、港澳台下级）。用于级联下拉。

③ 单条详情

act=detail

参数	必填	说明
id / code	二选一	节点 id 或 9 位区划代码

GET api.php?act=detail&code=370200000

{"ok":true,"data":{"id":15742,"code":"370200000","name":"青岛市","level":2,
 "type":"地级市","pinyin":"qingdaoshi","initial":"qds",
 "full_path":"全国/山东省/青岛市","postcode":"266000","areacode":"0532",
 "plates":"鲁B、鲁U","urban_cat":null,"urban_ratio":null,
 "urban_name":"","level_name":"地级","children_count":10}}

④ 搜索

act=search

参数	必填	说明
q	是	名称包含 / 拼音前缀 / 拼音首字母前缀
limit	否	默认 20，最大 500

GET api.php?act=search&q=sjz&limit=5 → 按首字母搜到「石家庄市」

也支持拼音：q=qingdao。补充单位与港澳台下级一并纳入搜索范围。

⑤ 村级

act=villages

参数

id（乡级节点 id，必填）、limit（默认 20，最大 500）

示例

GET api.php?act=villages&id=16333

返回

该乡级下辖的村 / 居委会：stat_code（统计局 12 位码）、name、cat（城乡分类）

⑥ 统计

act=stats

参数

无

返回

各级数量（levels）+ 数据来源与时点（meta）

口径与时点

调用前务必了解

两个数据源的时点不同，相差约 2.5 年：
· 行政区划（省/地/县/乡）为 2025-12-31 口径，来源民政部全国行政区划信息查询平台；
· 村级与城乡分类为 2023-06-30 口径，来源国家统计局（统计局自 2024-10 起不再公开具体代码）。
接口返回的 meta[].as_of 即各数据的标准时点。

邮编口径

为「区县主邮编」。同一区县内不同乡镇实际使用多个邮编，本数据取该区县常用代表邮编；乡级值由县区继承。

区号口径

国内长途区号。省级仅直辖市有值（本身即一个本地网）；12 个地区/自治州跨多个本地网，其地级值取所辖区县众数。

车牌口径

一市多号段按字母排序用「、」连接（如青岛鲁B、鲁U）。省级行存省简称；省/自治区的简称不向下继承。

城乡分类

官方「城乡分类代码」只编到村级，故乡级值为**按所辖村级汇总**的众数，另给 urban_ratio（城镇类村级占比）辅助判断。

补充单位

开发区/管理区等不属于民政部法定行政区划，单列于补充表；解析与浏览时会一并返回，type 即其类别。