一、技术简介
行政区划查询接口解决的是「把一串地名变成结构化区划数据」的问题。它的输入只有三样:层级(level)、区域名称(areaName)、页码(page);输出是一页区划记录,每条记录带主键、上级主键、完整名称、层级、邮编、区号、经纬度与拼音字段。
一次请求的处理链路可以拆成四步:
- 按
level指定要查哪一级:省、市、区县、乡镇、村委会; - 按
areaName收敛范围,名称越完整,命中越准; - 按
page翻页,单页有固定条数上限,页码也有上限; - 取回
data数组后,用id/parentId在本地建父子索引,后续查询走本地树。
接口本身是「一级一层」的取数模型:它不会一次把整棵树返回,也不会自动帮你判断上下级关系,层级关系要靠返回的 parentId、provinceId、cityId、countyId 自己串起来。
接口基本信息:
| 项目 | 说明 |
|---|---|
| 请求方式 | GET |
| 返回类型 | JSON |
| 鉴权方式 | 请求头 Authorization: APPCODE <appcode> |
| 参数个数 | 3 个(均可选,但实际至少应指定层级或名称) |
| 调用地址 | 以控制台中该接入点的调用地址为准,不自行拼接路径 |
| 字符编码 | UTF-8,中文名称直接返回,无需转码 |
| 单页条数 | 每页最多 20 条 |
| 页码上限 | 最大 100 页 |
本文基于公开接口文档与该接口公开使用说明整理,未对接口发起真实请求实测;示例返回用于说明字段形态,字段名与类型以接口文档为准。
二、能力概览
2.1 请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
level |
否 | string | 区域级别:1 省、2 市、3 区县、4 乡镇、5 村委会 |
areaName |
否 | string | 区域名称,尽量填完整,如「昆明市」 |
page |
否 | string | 当前页数,分页时使用,最大 100 页,每页最多 20 条 |
三个参数都标为选填,但工程上不能三个都不传:只传 page 等于在全量数据里盲翻,既拿不到稳定结果,也容易触发频次限制。稳妥的组合是「level + areaName」,page 只在候选超过 20 条时才用。
2.2 五级层级的实际差异
level 的取值是 1 到 5,但五个层级的字段完整度并不一致,这一点必须在建表阶段就认下来:
| level | 含义 | 典型名称 | 邮编 / 区号 | 数据密度 |
|---|---|---|---|---|
| 1 | 省级 | 省、自治区、直辖市 | 通常有 | 少,可一次取完 |
| 2 | 市级 | 地级市、地区、盟 | 通常有 | 中等 |
| 3 | 区县 | 市辖区、县、县级市 | 通常有 | 多 |
| 4 | 乡镇 | 街道、镇、乡、苏木 | 可能为空 | 很多 |
| 5 | 村委会 | 村、社区、居委会 | 多数字段为空 | 最多,需按名称收敛 |
公开文档对返回 level 的描述是「1 省级、2 市级、3 县级」,而参数说明里又给了 1 到 5 五档。两处表述并不完全一致,实际处理时以返回记录里的 level 值为准,不要按「2 一定是市、3 一定是区县」写死分支逻辑。

2.3 单条记录的字段构成
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 本区域主键,建本地树时作唯一键 |
parentId |
string | 上级区域主键,用于挂载父子关系 |
provinceId |
string | 所属省级主键 |
cityId |
string | 所属市级主键 |
countyId |
string | 所属区县主键 |
level |
string | 层级,1 到 5 |
areaName |
string | 区域名称,如「云南省」 |
wholeName |
string | 完整名称,含上级前缀,用于同名消歧 |
simpleName |
string | 中文简称 |
zipCode |
string | 邮政编码,低层级可能为空 |
areaCode |
string | 电话区号,低层级可能为空 |
lon / lat |
string | 经度、纬度,字符串形态 |
pinYin |
string | 名称全拼 |
simplePy |
string | 首字母简拼 |
prePinYin |
string | 名称拼音首字母 |
remark |
string | 备注,一般为空字符串 |
两个细节值得单独说:lon / lat 是字符串不是数字,入库前要显式转成浮点,否则排序会按字典序走;remark 文档明确「一般为空字符串」,不要拿它承载任何业务含义,也不要做非空判断当作有效字段。
三、适用场景
收货地址四级联动。 电商与本地生活的下单页需要省、市、区县、街道四层下拉,每一层都是一次按 level 与上级范围取数的请求,取回的 id 直接作为下一层的筛选依据。
共享出行与围栏。 停放区、运营区按行政区划划分时,需要区县级的名称与经纬度;围栏命名与区划名称同源,能避免运营侧与产品侧两套叫法。
地址库初始化。 一次性把五级数据拉全、落成本地表,之后对外只暴露 id 与名称;区划调整时按 id 做增量比对,而不是每次请求都重新拉一遍。
区域维度经营分析。 报表按省、市聚合时,把区划主键作为维度键,历史数据就不会因为名称变更而对不上口径。
地址文本解析的校验环节。 用户手填的地址在提交前拆出省市区县,与本地区划表比对,能挡掉「区县与市不匹配」这类脏数据。

四、接入流程
第一步:准备鉴权。 在云市场完成订购后,从控制台获取该接入点的 AppCode。AppCode 属于调用凭证,只能放在服务端密钥配置里,不得写进前端 JS、小程序包体或移动端代码。
第二步:确定层级口径。 先明确业务要的是几级:只做省市级报表就用 1 和 2;要做地址联动才需要 3 和 4。层级定得越窄,请求量越小,字段也越完整。
第三步:用名称收敛。 每一级都尽量给完整名称(「昆明市」而不是「昆明」),并带上层级一起传。只给简称时服务端可能返回多个候选,需要用 wholeName 二次核对。
第四步:处理分页。 单页最多 20 条、最多 100 页,也就是说单次「层级 + 名称」组合最多能取到 2000 条。深层级数据量超过这个窗口时,必须靠名称再切分区间。
第五步:落库与建索引。 以 id 为主键、parentId 为外键建树,把 provinceId / cityId / countyId 冗余存下来,避免每次展示都要递归回溯。

五、调用示例与返回结构
5.1 cURL
curl -G 'https://<控制台给出的调用地址>' \
-H 'Authorization: APPCODE <你的appcode>' \
--data-urlencode 'level=3' \
--data-urlencode 'areaName=昆明市' \
--data-urlencode 'page=1' \
--max-time 15
5.2 Python
import json
import requests
APPCODE = "你的appcode"
API_URL = "https://<控制台给出的调用地址>"
PAGE_SIZE = 20
MAX_PAGE = 100
def fetch_areas(level: int, area_name: str = "", page: int = 1) -> dict:
headers = {
"Authorization": f"APPCODE {APPCODE}", "Accept": "application/json"}
params = {
"level": str(level), "page": str(page)}
if area_name:
params["areaName"] = area_name
resp = requests.get(API_URL, params=params, headers=headers, timeout=15)
resp.raise_for_status()
payload = resp.json()
if payload.get("code") != 0: # 第一层:系统结果码
raise RuntimeError(f"system error: {payload.get('msg')}")
body = payload.get("body") or {
} # 第二层:业务节点
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"biz error: ret_code={body.get('ret_code')}")
rows = body.get("data") or [] # 第三层:结果数组
return {
"rows": rows, "has_more": len(rows) == PAGE_SIZE and page < MAX_PAGE}
def to_tree(level_rows: dict) -> list:
"""按 parentId 把多级结果拼成一棵树,lon / lat 显式转数字。"""
nodes = {
}
roots = []
for lv, rows in level_rows.items():
for r in rows:
nodes[r["id"]] = {
"id": r["id"],
"parent_id": r.get("parentId"),
"name": r["areaName"],
"whole": r.get("wholeName") or r["areaName"],
"level": int(r.get("level") or lv),
"zip_code": r.get("zipCode") or None, # 低层级可能为空串
"area_code": r.get("areaCode") or None,
"lon": float(r["lon"]) if r.get("lon") else None,
"lat": float(r["lat"]) if r.get("lat") else None,
"children": [],
}
for key, node in nodes.items():
parent = nodes.get(node.get("parent_id"))
if parent:
parent["children"].append(node)
else:
roots.append(node)
return roots
5.3 Java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
public class AreaClient {
private static final String APPCODE = "你的appcode";
private static final String API_URL = "https://<控制台给出的调用地址>";
private final HttpClient http = HttpClient.newBuilder()
.connectTimeout(java.time.Duration.ofSeconds(3))
.build();
public String query(int level, String areaName, int page) throws Exception {
String q = "level=" + level + "&page=" + page
+ (areaName == null || areaName.isEmpty() ? ""
: "&areaName=" + URLEncoder.encode(areaName, StandardCharsets.UTF_8));
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create(API_URL + "?" + q))
.header("Authorization", "APPCODE " + APPCODE)
.timeout(java.time.Duration.ofSeconds(15))
.GET()
.build();
HttpResponse<String> resp = http.send(req,
HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
if (resp.statusCode() != 200) {
throw new IllegalStateException("http " + resp.statusCode());
}
return resp.body(); // 交给 JSON 库解析,再逐层判 ret_code 与 data
}
}
5.4 返回结构
外层是统一包装,业务数据在 body 里,具体字段名以接口文档为准。下面用 code / msg / body / ret_code / data 代指各部分:
{
"code": 0,
"msg": "success",
"body": {
"ret_code": 0,
"data": [
{
"id": "530100",
"parentId": "530000",
"provinceId": "530000",
"cityId": "530100",
"countyId": "",
"level": "2",
"areaName": "昆明市",
"wholeName": "云南省昆明市",
"simpleName": "昆明",
"zipCode": "650000",
"areaCode": "0871",
"lon": "102.712251",
"lat": "25.040609",
"pinYin": "kunmingshi",
"simplePy": "kms",
"prePinYin": "kms",
"remark": ""
}
]
}
}
以上为示例返回,仅用于说明字段形态,不代表真实调用结果;数值与空值以实际返回为准。

六、调试方法与示例返回
调试阶段建议按「由粗到细」的顺序做,一次只改一个参数:
- 只传
level=1,page=1。 先确认鉴权通过、返回结构对得上,此时结果集最小,出问题时变量最少。 - 加上
areaName。 用完整名称(「云南省」),观察data是否从多条收敛为一条;如果条数没变,说明名称没匹配上,先换全称再试。 - 加
page=2。 检查第 2 页是否仍有数据、id是否与第 1 页重复。出现重复说明服务端排序不稳定,翻页时应以id去重。 - 逐级下钻。 用上一级返回的
id作为范围线索,再查下一级,直到level=4。这一步能提前暴露「某地没有第 4 级数据」的空结果。 - 对比字段完整度。 分别取
level=3与level=4的同名区域,比较zipCode、areaCode是否有值,决定表结构里这两个字段是否允许为空。
调试面板里只填参数、看返回,不要拿生产 AppCode 反复压测;每轮调试结束后把请求参数记进联调记录,方便对比前后两次的差异。
七、五个高频坑与规避方案
标题里说的「避坑」,指的就是下面这五处。它们都不在参数表里,只能靠取数顺序绕开。
坑 1:把 level 当成固定四级。 直辖市的层级结构与普通省不同,省直辖县级市也可能直接挂在省级下。规避方式是按返回的 level 值判断,而不是按「省 → 市 → 区县」的位置硬编码;遇到层级跳跃时,以 parentId 链路为准。
坑 2:areaName 只传简称。 传「昆明」可能匹配不到「昆明市」,也可能一次返回多个同音或同名的候选。规避方式是传完整名称,并在拿到结果后用 wholeName 复核是否是要的那一条。
坑 3:深层级只靠翻页。 单页 20 条、最多 100 页,level=4、level=5 的数据量远超这个窗口。规避方式是先用上级名称把范围收敛到一个市或一个区县,再在范围内翻页;仍然取不全时,按名称前缀继续切分。
坑 4:默认邮编区号一定存在。 乡镇与村级记录的 zipCode、areaCode 可能为空字符串。规避方式是把这两个字段设计成可缺省,展示层统一走「有值显示、无值留空」,不要用 null 判断代替空串判断。
坑 5:同名区县直接入库。 多个城市都存在同名市辖区,只用 areaName 当唯一键会互相覆盖。规避方式是用 provinceId + cityId + areaName 组合去重,主键仍用 id。
这五处的共同解法是同一套取数顺序:先取上级、再取本级、最后按
id关联。

八、调用限制与规范
| 限制项 | 口径 | 工程建议 |
|---|---|---|
| 单页条数 | 每页最多 20 条 | 不要期望一次取全,按层级 + 名称切分 |
| 页码上限 | 最大 100 页 | 超过 2000 条的场景必须重新设计取数范围 |
| 鉴权 | 请求头 Authorization: APPCODE <appcode> |
凭证只存服务端,按环境隔离 |
| 传输 | 连接超时 3 秒、读超时 15 秒 | 超时后重试最多 3 次,指数退避 |
| 幂等 | GET 幂等,可重复取数 | 同一组参数可直接命中本地缓存 |
| 数据缓存 | 区划数据变更频率低 | 本地全量落库,按月做一次增量比对 |
区划调整属于低频事件,通常按年度公告批量发布。把接口当成「初始化 + 定期校对」的数据源,比当成实时查询接口更省调用量,也更稳。
九、能力边界与免责
- 层级深度以返回为准。 部分区域的第 4、5 级数据可能不完整,接口返回空数组时,应视为「该范围没有该层级数据」,而不是接口异常。
- 经纬度坐标系未在文档标注。 需要与地图底图叠加时,先自行做一次坐标校准,不要默认与某种坐标系一致。
- 名称口径可能随区划调整变化。 撤县设区、乡镇合并会导致名称与层级变化,历史数据要保留快照版本号,避免新旧口径混算。
- 不作为法定地址依据。 接口返回用于系统内部校验与展示,涉及合同、司法、行政登记的地址,仍应以官方发布为准。
- 数据合规。 区划数据属于公开信息,但与用户地址组合后即为个人信息,采集与存储需遵循最小必要原则,日志中的完整地址应做脱敏。
十、错误码排查
接口的错误分两层:HTTP 状态码说明请求本身是否成立,业务码 ret_code 说明业务是否跑通。两层都过才算成功。
| HTTP 状态 | 常见含义 | 先查这一项 |
|---|---|---|
| 400 | 参数缺失或取值不合法 | level 是否在 1~5,page 是否为正整数 |
| 401 / 403 | AppCode 无效、未订购或请求头格式错 | 请求头是否为 Authorization: APPCODE <appcode> |
| 404 | 调用地址路径写错 | 地址是否与控制台给出的接入点完全一致 |
| 429 | 并发或频次超限 | 降并发、加退避,先读本地缓存 |
| 450 | 系统通过、业务失败 | 看 ret_code 与描述文本,常见为名称未匹配 |
| 5xx | 服务端异常 | 限量重试,记录请求时间与参数再反馈 |
排查时把 ret_code 和描述文本一并记录。只留 HTTP 状态,会丢掉最有用的业务原因;反过来只留业务码,也定位不到鉴权与路径问题。

十一、技术 FAQ
Q1:三个参数都不传会怎样?
会退化成在全量数据里按默认顺序翻页,结果不稳定,也拿不到有意义的分页边界。至少传 level。
Q2:能不能一次拿到整棵树?
不能。接口按「一级一层」返回,整棵树要在本地用 parentId 拼装。首次初始化可以按层级逐层拉取,之后就只用增量比对。
Q3:areaName 传全称还是简称?
传全称命中率更高。简称可以作为二次尝试,但要接受多候选并用 wholeName 复核。
Q4:乡镇与村级的邮编、区号为什么是空的?
低层级数据在公开口径上并不保证包含邮编与区号,字段存在但值可能为空串。表结构应允许为空。
Q5:分页翻到第 100 页还没取完怎么办?
说明当前范围已经超过接口的单次返回窗口,需要用名称把范围切小,或改为按上级逐段拉取,而不是继续加页码。
Q6:id 会变吗?
区划调整时可能出现新增与合并,主键通常保持稳定,但不能假设永久不变。对外暴露时保留一层自有 ID 映射,比直接透出上游主键更安全。
十二、内容小结
行政区划查询接口的技术难度不在参数,而在三件事:层级口径、名称收敛、分页边界。把这三件事在接入阶段定下来,后续的地址联动、围栏划分、报表聚合都能复用同一张本地区划表。
落地时的最小闭环是:服务端持有 AppCode → 按 level 逐层取数 → 用 areaName 收敛范围 → id 建主键、parentId 建树 → 按月做一次增量校对。做到这一步,区划就从一个「要查的接口」变成了系统里一张稳定的基础字典。