行政区划查询：5 分钟接入，从注册到第一条区划数据
# 行政区划查询：5 分钟接入，从注册到第一条区划数据
> 接口 / 接入点：行政区划查询（apiCode 1149）· 区域查询 1149-1 · 子区域查询 1149-2 · **免费服务**
> 请求方式：POST / GET · 返回格式：JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 行政区划查询是**免费接口**，注册后拿到 AppKey 即可调用，零成本试用。
- 区域查询（1149-1）靠 `areaName`（必填）+ `level` 检索；子区域查询（1149-2）靠 `parentId`（必填）下钻。
- 返回体业务数据都包在 `showapi_res_body` 里，`data` 是数组，每条包含 `wholeName`、`id`、`zipCode` 等字段。
## Why：为什么值得 5 分钟接入
做表单、收货地址、用户属地统计时，你迟早要面对「省市区三级怎么选、区号邮编怎么带」的问题。与其自己维护一份容易过时的行政区划表，不如直接调用官方接口——数据每月同步民政部，覆盖到村委会级别，而且**免费**。这 5 分钟，能省下你后面反复维护字典的成本。
## What：前置条件与接口速览
| 项 | 说明 |
|----|------|
| 接口名称 | 行政区划查询（apiCode 1149） |
| 服务商 | 昆明秀派科技有限公司（万维易源官方自营） |
| 是否免费 | **免费服务** |
| 接入点 | 1149-1 区域查询 / 1149-2 子区域查询 |
| 请求方式 | POST / GET |
| 返回格式 | JSON |
| 鉴权 | AppKey（放在 query 参数 `appKey` 或 Header） |
| 更新频率 | 每月 1-3 号早上 9 点检查民政部数据并更新 |
| 集成能力 | MCP 服务、OpenAPI 3.0（YAML / JSON） |
前置条件：一个 ShowAPI 账号 + 一个 AppKey（[控制台获取](https://www.showapi.com/console#/myApp)）。
## How：第一次调用
下面以「查昆明市（`areaName=昆明市`，`level=2` 市级）」为例。把 `YOUR_APPKEY` 换成你的真实 AppKey 即可运行。
### Python（requests）
```python
import requests
url = "https://route.showapi.com/1149-1"
params = {
"appKey": "YOUR_APPKEY", # 替换为你的真实 AppKey
"areaName": "昆明市",
"level": "2", # 1省 2市 3区县 4乡镇 5村委会，默认 2
"page": "1",
}
try:
r = requests.get(url, params=params, timeout=10)
r.raise_for_status()
data = r.json()
if data.get("showapi_res_code") != 0:
print("系统级错误:", data.get("showapi_res_error"))
else:
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
print("业务错误:", body.get("msg"))
else:
for item in body["data"]:
print(item["wholeName"], "| id=", item["id"], "| 邮编", item["zipCode"])
except requests.RequestException as e:
print("请求失败:", e)
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1149-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "level=2&areaName=%E6%98%86%E6%98%8E%E5%B8%82&page=1"
```
### Node.js（fetch）
```javascript
const url = "https://route.showapi.com/1149-1?appKey=YOUR_APPKEY"
+ "&level=2&areaName=" + encodeURIComponent("昆明市") + "&page=1";
fetch(url, { method: "GET" })
.then(r => r.json())
.then(data => {
const body = data.showapi_res_body;
if (body.ret_code !== 0) { console.error("业务错误:", body.msg); return; }
body.data.forEach(item => console.log(item.wholeName, "| id=", item.id, "| 邮编", item.zipCode));
})
.catch(e => console.error("请求失败:", e));
```
## 返回示例与解析
```json
{
"showapi_res_error": "",
"showapi_res_code": 0,
"showapi_res_id": "60dad1030de376f451c820ac",
"showapi_res_body": {
"ret_code": 0,
"page": 1,
"data": [
{
"provinceId": "530000000000",
"simpleName": "昆明",
"cityId": "530100000000",
"areaCode": "0871",
"prePinYin": "K",
"id": "530100000000",
"pinYin": "kun ming shi",
"parentId": "530000000000",
"level": 2,
"areaName": "昆明市",
"simplePy": "KM",
"zipCode": "650000",
"countyId": "",
"wholeName": "中国,云南省,昆明市"
}
],
"allNum": 1,
"msg": "查询成功",
"maxSize": 20,
"allPage": 1
}
}
```
解析要点：
- `showapi_res_code` 是**系统级**状态码，`0` 表示请求本身成功；业务结果看 `showapi_res_body.ret_code`。
- `data` 是**数组**，即使只有一条结果也是数组，遍历取值。
- `wholeName` 是逗号分隔的全称（如 `中国,云南省,昆明市`），适合直接展示。
- `id` 就是该区域的编码，做下钻时把它传给子区域查询的 `parentId`。
## 进阶 / 边界
- `areaName` 越完整越准确：写「昆明」可能返回多条，写「昆明市」更精准。
- `lon` / `lat` 字段已**废弃**，`location` 未说明坐标系，不要拿它们做地图标点，需要坐标请走外部地理编码。
- 分页：每页最多 20 条，最多 50 页；结果多时用 `page` 翻页。
## FAQ
**Q：接口真的免费吗？会不会有隐藏计费？**
免费服务，页面明确标注「免费服务」，无按次 / 按单 / 资源包计费。以官方接口详情页为准。
**Q：areaName 不填会怎样？**
`areaName` 是区域查询（1149-1）的必填项，不填将无法定位区域，返回的业务 `msg` 会提示参数问题。
**Q：返回的 id 能直接用于子区域查询吗？**
可以。把区域查询返回的 `id` 作为子区域查询（1149-2）的 `parentId` 传入，即可下钻它的下级区域。
**Q：showapi_res_code 和 ret_code 有什么区别？**
`showapi_res_code` 是系统级（请求是否到达并正常处理），`ret_code` 是 `showapi_res_body` 内的业务级（业务是否查到数据）。判断成功应两者都看。
## 相关能力 / 下一步阅读
- [行政区划查询返回字段全解：wholeName / 各级编码 / 拼音一文读懂](https://www.showapi.com/guides/region-query-response-fields-1149)
- [行政区划查询子区域查询实战：用 parentId 逐级下钻省→市→区→街道](https://www.showapi.com/guides/region-query-subregion-1149)
- **本系列共 11 篇**：查看[行政区划查询指南总目录](https://www.showapi.com/guides/region-query-guides-1149)
