产品

五级行政区划查询 API

省、市、县、乡镇、村五个级别,全国 665,552 条,一个接口查完。

数据版本 2024 年度统计用区划代码6 个接口按次 / 包月 / 包季 / 包年

数据构成

各级别收录数量,随国家统计局年度统计用区划代码更新。

可用
省级(level 1)31 条地级(level 2)343 条县级(level 3)3,255 条乡镇级(level 4)41,351 条村级(level 5)620,572 条合计665,552 条

省级 31 条为 22 个省、5 个自治区、4 个直辖市,不含香港、澳门特别行政区与台湾省。

它解决什么问题

地址表单的省市区联动

用「下级列表」接口逐级下钻,前端拿到的就是带代码的标准名称,不用自己维护一份会过期的 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。

111主城区112城乡结合区121镇中心区122镇乡结合区123特殊区域210乡中心区220村庄

路径会跳级,请按 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 一起提供。

下级列表取北京市市辖区(1101)的下级
{
  "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"
}

套餐

先用免费试用跑通,再按真实用量选。完整对比与计费规则在定价页。

免费试用

7 天内用完 1,000 次
免费
1,000 次 · QPS 21 个 Key

按量充值

余额有效期 1 年
0.0058元 / 次
自选金额 · QPS 103 个 Key

包月

日上限 2 万次
¥29/ 月
30 万次 · QPS 205 个 Key

包季

不设日上限
¥79/ 季
100 万次 · QPS 205 个 Key

常见问题

计费口径到底是什么

只有成功调用才扣减额度,判定标准是 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,提示运维去控制台续费,而不是当成通用错误重试。

十分钟跑通第一次调用

注册拿 Key,复制文档里的示例直接跑,六种语言都有。