邮编区域互查·查询详细地区邮编（接入点3）实战：省市区三级联动查询
邮编查询邮编区域互查ShowAPI免费接口API教程 # 邮编区域互查·查询详细地区邮编（接入点3）实战：省市区三级联动查询
> 邮编区域互查（apiCode=1917）· 接入点3 查询详细地区的邮编 · 免费接口 · 初级~中级开发者 · 约 8 分钟
## 核心要点
- 接入点3（`1917-3`）按 `province`/`city`/`area`/`county` 逐级筛选，返回邮编（字段名 `code`）。
- 适合「已知省市区，想拿精确邮编」的场景，常做表单三级联动的最后一环。
- ⚠️ **实测差异（重要）**：在免费档位下，传 `province=云南省`（含 `city`/`area`/`county` 组合）返回 `ret_code:0, msg:"查询成功"` 但 **`contentlist` 为空数组**（`allNum:1000, allPages:50`）。文档返回示例显示有数据，与实测不符。
## Why：靠逐级筛选拿精确邮编
相比接入点2 只传一个 `area`，接入点3 支持省/市/区/街道四个维度组合，更适合在地址选择器里逐级下钻、精确取邮编。但**务必先在你的档位下自测确认数据是否返回**，不要默认一定有结果。
## What：接口速览
| 项 | 说明 |
|----|------|
| 接入点地址 | `https://route.showapi.com/1917-3?appKey={your_appKey}` |
| 请求参数 | `province`(省)、`city`(市)、`area`(区县)、`county`(街道)、`page`(页码，文档标注分页最大 50 页) |
| 返回邮编字段名 | `code` |
| 计费 | 免费（有使用档次限制） |
## How：省市区联动查询
### Python
```python
import requests
def detail_zip(app_key, province, city=None, area=None, county=None, page=1):
params = {"appKey": app_key, "province": province, "page": page}
if city: params["city"] = city
if area: params["area"] = area
if county: params["county"] = county
r = requests.post("https://route.showapi.com/1917-3", params=params, timeout=10)
data = r.json()
if data.get("showapi_res_code") != 0:
return None, data.get("showapi_res_error")
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
return None, body.get("msg")
# 注意：免费档位下 contentlist 可能为空，须判空
return body.get("contentlist", []), None
items, err = detail_zip("YOUR_APPKEY", "云南省", city="昆明市", area="西山区")
if err:
print("失败:", err)
elif not items:
print("ret_code=0 但 contentlist 为空（免费档位可能未返回数据行，请自测确认）")
else:
for it in items:
print(it["province"], it["city"], it["area"], it["county"], "邮编", it["code"])
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1917-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "province=云南省" --data-urlencode "city=昆明市" \
--data-urlencode "area=西山区" --data-urlencode "page=1"
```
### Node.js（fetch）
```javascript
const params = new URLSearchParams({ appKey: "YOUR_APPKEY", province: "云南省", city: "昆明市", area: "西山区", page: "1" });
const res = await fetch(`https://route.showapi.com/1917-3?appKey=YOUR_APPKEY`,
{ method: "POST", body: params, signal: AbortSignal.timeout(10000) });
const data = await res.json();
const b = data.showapi_res_body;
if (b.ret_code !== 0) throw new Error(b.msg);
if (!b.contentlist || b.contentlist.length === 0) console.log("空列表，请确认档位数据");
else console.log(b.contentlist);
```
## 返回示例与解析（实测：免费档位空列表）
```json
{
"showapi_res_body": {
"ret_code": 0, "msg": "查询成功",
"contentlist": [],
"maxResult": 20, "allNum": 1000, "allPages": 50, "currentPage": 1
}
}
```
> `ret_code` 为 0、`allNum` 却显示 1000，但 `contentlist` 为空——这是免费档位下的实测现象，**不要据此断言接口「无数据」**，应先在你的账号档位下确认。
## 进阶/边界
- **先自测再上线**：在目标档位下用真实参数跑一次，确认 `contentlist` 有数据再写业务逻辑。
- **分页上限**：文档标注 `page` 最大 50 页，超范围按接口约束处理。
- **字段名**：接入点3 邮编字段是 `code`（与接入点2 的 `postcode` 不同）。
- **兜底**：若接入点3 在你的档位下无数据，可退回接入点2（传区/县名）获取邮编。
## FAQ
**Q1：为什么我查出来 `contentlist` 是空的？**
免费档位下实测会出现 `ret_code:0` 但空列表的情况；请先在你的档位自测确认数据是否开放。
**Q2：接入点3 和接入点2 有什么区别？**
接入点3 支持省/市/区/街道多级筛选；接入点2 只传一个 `area` 且返回字段叫 `postcode`。
**Q3：邮编字段叫什么？**
接入点3 是 `code`。
**Q4：分页最大多少页？**
文档标注最大 50 页。
**Q5：返回 `allNum:1000` 但列表为空正常吗？**
免费档位实测如此，属数据开放范围问题，非代码错误。
## 相关能力 / 下一步阅读
- [邮编区域互查·地区查邮编（接入点2）实战](https://www.showapi.com/guides/postcode-region-to-zip-1917)
- [邮编区域互查错误码排查](https://www.showapi.com/guides/postcode-error-codes-1917)
- [邮编区域互查分页与 maxResult/allNum 实战](https://www.showapi.com/guides/postcode-pagination-1917)
- **本系列共 12 篇**：查看[邮编区域互查指南总目录](https://www.showapi.com/guides/postcode-guides-1917)
