它解决什么问题
地址表单的省市区联动
用「下级列表」接口逐级下钻,前端拿到的就是带代码的标准名称,不用自己维护一份会过期的 JSON。
存量地址的标准化与校验
用「名称搜索」匹配历史数据里的非标准写法,再用「区划详情」拿到权威代码与完整路径,统一入库。
统计口径对齐
业务数据按统计用区划代码归集,和国家统计局的口径一致,跨系统汇总时不会因为名称写法不同而对不上。
本地缓存的增量同步
用「子树」接口一次导出某个省或市的完整下级,落到自己的库里,按年度做一次全量比对即可。
五个级别与代码规则
统计用区划代码为 12 位数字:前 6 位是县级及以上行政区划代码,第 7 到 9 位是乡镇级,第 10 到 12 位是村级。接口统一返回 12 位代码;请求时也可以传 2 / 4 / 6 / 9 位短码,会在右侧自动补零,例如 110105 等于 110105000000。
| 级别 | level | 包含 | 有效位数 | 示例 | 数量 |
|---|---|---|---|---|---|
| 省级 | 1 | 省、自治区、直辖市 | 前 2 位(其余补 0) | 110000000000 北京市 | 31 |
| 地级 | 2 | 地级市、自治州、地区、盟 | 前 4 位(其余补 0) | 130100000000 石家庄市 | 343 |
| 县级 | 3 | 市辖区、县级市、县、自治县、旗 | 前 6 位(其余补 0) | 110105000000 朝阳区 | 3,255 |
| 乡镇级 | 4 | 街道、镇、乡、民族乡、苏木 | 前 9 位(其余补 0) | 110105001000 建外街道 | 41,351 |
| 村级 | 5 | 居委会、村委会 | 12 位 | 110105001024 南郎家园社区居委会 | 620,572 |
城乡分类代码
字段 category / category_name,只在村级(level 5)记录上有值,其他级别为 null。
路径会跳级,请按 level 读
不是所有行政区划都有完整五层。path 数组的长度不固定,请根据每个节点的 level 字段判断它是哪一级,不要假设固定五层或按下标取值。
北京、天津、上海、重庆的地级(level 2)是「市辖区」(重庆另有「县」)这类占位名称,区县在它们之下;省直辖的县级市同理,挂在「省直辖县级行政区划」下。full_name 不拼入占位名称,例如朝阳区的 path 是 北京市 / 市辖区 / 朝阳区,full_name 是「北京市朝阳区」。
广东东莞市、中山市,甘肃嘉峪关市,海南儋州市是不设区的地级市,下级直接是乡镇级(level 4),没有县级(level 3)。
六个接口
全部用同一个 API Key 鉴权,同一份额度扣减。除批量查询外,一次请求计 1 次。
| 接口 | 方法与路径 | 用途 | 计费 |
|---|---|---|---|
| 区划详情 | GET /area/v1/regions/{code} | 按代码取单条记录,返回名称、层级、上级代码与完整路径。 | 1 次 |
| 下级列表 | GET /area/v1/regions/{code}/children | 取某个区划的直接下级,省市区联动就用这个。 | 1 次 |
| 条件列表 | GET /area/v1/regions | 按 level、pcode、category 筛选并分页,适合批量拉取。 | 1 次 |
| 名称搜索 | GET /area/v1/regions/search | 按名称模糊匹配,可用 level、within 限定范围,用于历史地址标准化。 | 1 次 |
| 子树 | GET /area/v1/regions/{code}/tree | 一次导出某节点往下一到两层的完整子树,用 depth 控制深度。 | 1 次 |
| 批量查询 | POST /area/v1/regions/batch | 一次请求查多个代码,最多 100 个。 | 按代码个数计费 |
响应示例
所有接口共用同一层信封:code、message、data、request_id。排查问题时请把 request_id 一起提供。
{
"code": 0,
"message": "ok",
"data": {
"items": [
{
"code": "110101000000",
"name": "东城区",
"level": 3,
"level_name": "县级",
"parent_code": "110100000000",
"category": null,
"category_name": null,
"full_name": "北京市东城区"
},
{
"code": "110102000000",
"name": "西城区",
"level": 3,
"level_name": "县级",
"parent_code": "110100000000",
"category": null,
"category_name": null,
"full_name": "北京市西城区"
},
{
"code": "110105000000",
"name": "朝阳区",
"level": 3,
"level_name": "县级",
"parent_code": "110100000000",
"category": null,
"category_name": null,
"full_name": "北京市朝阳区"
}
],
"total": 16,
"page": 1,
"size": 100
},
"request_id": "01a1de46-02c7-7b1e-9f4a-3c58d2e1a7b0"
}# 请求
POST /area/v1/regions/batch
{ "codes": ["110105", "441900", "999999"] }
# 响应:计费 3 次(按去重后的代码个数)
{
"code": 0,
"message": "ok",
"data": {
"items": [
{
"code": "110105000000",
"name": "朝阳区",
"level": 3,
"level_name": "县级",
"parent_code": "110100000000",
"category": null,
"category_name": null,
"full_name": "北京市朝阳区",
"path": [
{ "code": "110000000000", "name": "北京市", "level": 1 },
{ "code": "110100000000", "name": "市辖区", "level": 2 },
{ "code": "110105000000", "name": "朝阳区", "level": 3 }
]
},
{
"code": "441900000000",
"name": "东莞市",
"level": 2,
"level_name": "地级",
"parent_code": "440000000000",
"category": null,
"category_name": null,
"full_name": "广东省东莞市",
"path": [
{ "code": "440000000000", "name": "广东省", "level": 1 },
{ "code": "441900000000", "name": "东莞市", "level": 2 }
]
}
],
"not_found": ["999999000000"]
},
"request_id": "01a1de46-5d18-7c42-8e0b-71f9a4c2d6e3"
}常见问题
计费口径到底是什么
只有成功调用才扣减额度,判定标准是 HTTP 200 且响应体里的 code 等于 0。
参数错误(40001)、鉴权失败(401xx)、IP 不在白名单(40301)、区划不存在(40401)、请求过于频繁(42901)都不计费。批量查询按请求里传入的代码个数计费,传 50 个就计 50 次。
缓存命中还计费吗
计费。缓存是我们保证响应速度的手段,不改变计费口径,命中缓存的成功调用同样扣 1 次。
如果你的查询高度集中在少数几个区划,建议在自己这一侧也做一层缓存,或者用「子树」接口一次导出后本地查询,这样更省额度。
数据多久更新一次
按年度更新,跟随国家统计局发布的统计用区划代码。当前数据版本是 2024 年度;所有接口都支持可选参数 version(数据年度),不传时取当前版本。
年度更新上线前会在更新日志公告,接口结构不变,不需要你改代码。
额度用完或套餐到期了怎么办
接口会返回 HTTP 402,业务码区分三种情况:没有有效套餐(40201)、额度用尽(40202)、超出日限额(40203)。响应里的 data.renew_url 是续费或订购页面的地址。
续费或充值后立即恢复,API Key、IP 白名单和所有配置都不变,不需要重新接入。建议在代码里单独处理 402,提示运维去控制台续费,而不是当成通用错误重试。