行政区划查询返回字段全解：wholeName / 各级编码 / 拼音一文读懂
# 行政区划查询返回字段全解：wholeName / 各级编码 / 拼音一文读懂
> 接口 / 接入点：行政区划查询（apiCode 1149）· 区域查询 1149-1 / 子区域查询 1149-2 · 免费服务
> 请求方式：POST / GET · 返回格式：JSON · 适用人群：已接入开发者、需要字段语义的工程师 · 阅读时间：约 6 分钟
## 核心要点
- 业务数据全部包在 `showapi_res_body` 里，`data` 是数组，每条代表一个区域。
- 编码字段成体系：`provinceId` / `cityId` / `countyId` / `townId` / `villageId` / `parentId` / `id`，呈「上级 → 本级」层级关系。
- `wholeName` 是逗号分隔全称，`lon` / `lat` 已废弃，`location` 未说明坐标系，地图需求请走外部地理编码。
## Why：为什么要把字段搞清楚
接入后第一道坎往往是「返回这么多字段，哪个是我要的？」——做展示用 `wholeName`，做联动用 `id`/`parentId`，做拼音检索用 `pinYin`/`simplePy`，做地址校验用 `areaCode`/`zipCode`。这一篇把字段语义一次讲清，省得你每篇都翻文档。
## What：返回结构速览
系统级封装字段（所有 ShowAPI 接口通用）：
| 字段 | 类型 | 说明 |
|------|------|------|
| showapi_res_code | Number | 系统级状态码，0 成功 |
| showapi_res_error | String | 系统级错误信息 |
| showapi_res_id | String | 本次请求 ID |
| showapi_res_body | Object | 业务数据容器 |
`showapi_res_body` 业务字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| ret_code | Number/String | 业务级状态码，0 成功 |
| page | Number | 当前页 |
| allNum | Number | 总数据条数 |
| maxSize | Number | 每页最大 20 条 |
| allPage | Number | 最大分页值 |
| msg | String | 提示信息 |
| upgrade_info | String | 使用及更新要点 |
| data | Object[] | 区域列表 |
`data[]` 单项字段（区域查询 1149-1 与子区域查询 1149-2 略有差异，下表标注）：
| 字段 | 说明 | 备注 |
|------|------|------|
| id | 区域 id（本级编码） | 下钻时作 `parentId` 使用 |
| parentId | 上级编码 | 与 `id` 形成层级链 |
| provinceId | 省级编码 | 如 530000000000 |
| cityId | 市级编码 | — |
| countyId | 区县编码 | 子区域查询也返回 |
| townId | 乡镇 id | 区域查询 1149-1 有，子区域查询 1149-2 无 |
| villageId | 村委会 / 乡镇 id | — |
| areaName | 区域名称 | 如「昆明市」 |
| simpleName | 区域名简称 | 如「昆明」 |
| wholeName | 全称（逗号分隔） | 如「中国,云南省,昆明市」 |
| areaCode | 区号 | 如 0871 |
| zipCode | 邮编 | 如 650000 |
| level | 行政级别 | 1省 2市 3区县 4乡镇 5村委会（区域查询）；子区域查询返回 1~3 |
| pinYin | 全拼 | 如 kun ming shi |
| simplePy | 简拼 | 如 KM |
| prePinYin | 拼音首字母 | 如 K |
| remark | 备注 | 仅子区域查询 1149-2 返回 |
| lon / lat | 经度 / 纬度 | **已废弃**，勿用于地图 |
| location | 坐标 | 文档未说明坐标系与格式，示例为空 |
## How：用字段拼出层级
`parentId` 与各级编码的关系是固定的：省级的 `parentId` 为空（或本国根），市级的 `parentId` 等于其 `provinceId`，区县的 `parentId` 等于其 `cityId`，以此类推。利用这个关系，你可以从任意一条记录反推它的完整上级链。
```python
import requests
def query(area_name, level="2"):
r = requests.get("https://route.showapi.com/1149-1",
params={"appKey": "YOUR_APPKEY", "areaName": area_name, "level": level},
timeout=10)
body = r.json()["showapi_res_body"]
return body["data"]
for item in query("昆明市"):
print("全称:", item["wholeName"])
print("本级id:", item["id"], "| 上级parentId:", item["parentId"])
print("省编码:", item["provinceId"], "| 市编码:", item["cityId"], "| 区号:", item["areaCode"])
```
## 返回示例（子区域查询 1149-2）
```json
{
"showapi_res_body": {
"ret_code": "0",
"data": [
{
"provinceId": "440000000000",
"simpleName": "荔湾",
"areaCode": "020",
"cityId": "440100000000",
"remark": "",
"pinYin": "Liwan",
"prePinYin": "L",
"parentId": "440100000000",
"level": "3",
"areaName": "荔湾区",
"simplePy": "Lw",
"zipCode": "510000",
"countyId": "440103000000",
"wholeName": "",
"villageId": ""
}
],
"page": "1",
"allNum": "1",
"maxSize": "20",
"allPage": "1"
}
}
```
注意：子区域查询的 `ret_code` / `page` / `allNum` 等字段在文档示例中为**字符串**类型，区域查询为**数字**类型。解析时建议做容错（如 `int(x)` 前先判断），不要假设固定类型。
## 进阶 / 边界
- `townId` 只在区域查询（1149-1）出现；做「乡镇级」下钻时优先用区域查询 + `level=4/5`。
- `wholeName` 在区域查询有值、子区域查询示例为空——若需要全称，建议在区域查询层取。
- 不要依赖 `lon`/`lat`（已废弃）和 `location`（未说明格式）做地理计算。
## FAQ
**Q：data 是对象还是数组？**
是**数组**（Object[]）。即使只命中一条，也要按数组遍历。
**Q：为什么有的字段是空字符串？**
乡镇 / 村委会等下级编码在上级区域里为空（如市级记录的 `countyId` 为空），这是正常的层级空缺，不是接口 bug。
**Q：ret_code 在文档里是 Number 还是 String？**
两个接入点不一致：区域查询示例为 Number，子区域查询示例为 String。解析时做类型容错更稳妥。
**Q：lon / lat 还能用吗？**
页面明确标注「废弃」，建议忽略；需要经纬度请使用外部地理编码服务。
## 相关能力 / 下一步阅读
- [行政区划查询：5 分钟接入，从注册到第一条区划数据](https://www.showapi.com/guides/region-query-quickstart-1149)
- [行政区划查询子区域查询实战：用 parentId 逐级下钻省→市→区→街道](https://www.showapi.com/guides/region-query-subregion-1149)
- **本系列共 11 篇**：查看[行政区划查询指南总目录](https://www.showapi.com/guides/region-query-guides-1149)
