邮编区域互查·邮编查地区（接入点1）实战：快递物流与地址验证怎么用
邮编查询邮编区域互查ShowAPI免费接口API教程 # 邮编区域互查·邮编查地区（接入点1）实战：快递物流与地址验证怎么用
> 邮编区域互查（apiCode=1917）· 接入点1 邮编查询区域 · 免费接口 · 初级~中级开发者 · 约 8 分钟
## 核心要点
- 接入点1（`1917-1`）是「邮编 → 地区」：传入 6 位 `code`，返回省/市/区/街道与电话区号。
- 实测可用、数据真实（如 `362504`→福建泉州德化县；`200000`→上海辖区）。
- 一个邮编可能对应多条街道，用 `page` 翻页取全；返回含未文档化的 `areacode`。
## Why：只有邮编时，它最有用
用户填了邮编、没填详细地址？表单只收集到邮编？快递面单只有邮编？接入点1 帮你把邮编补成完整行政区划，做地址校验、按地区分单、地图归属都方便。
## What：接口速览
| 项 | 说明 |
|----|------|
| 接入点地址 | `https://route.showapi.com/1917-1?appKey={your_appKey}` |
| 请求参数 | `code`（6 位邮编，非必填）、`page`（页码，非必填） |
| 返回邮编字段名 | `code` |
| 计费 | 免费（有使用档次限制） |
## How：邮编查地区
### Python
```python
import requests
def zip_to_region(app_key, code, page=1):
r = requests.post("https://route.showapi.com/1917-1",
params={"appKey": app_key, "code": code, "page": page}, 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")
return body.get("contentlist", []), None
items, err = zip_to_region("YOUR_APPKEY", "362504")
if err:
print("查询失败:", err)
else:
for it in items:
print(it["province"], it["city"], it["area"], it["county"], "区号", it.get("areacode"))
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1917-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "code=362504" --data-urlencode "page=1"
```
### Node.js（fetch）
```javascript
const res = await fetch(`https://route.showapi.com/1917-1?appKey=YOUR_APPKEY`,
{ method: "POST", body: new URLSearchParams({ code: "362504", page: "1" }),
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);
console.log(b.contentlist);
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": 0, "code": "362504", "msg": "查询成功！",
"contentlist": [
{"area":"德化县","county":"国宝乡上洋村","city":"泉州市","province":"福建省","areacode":"0595","code":"362504"}
],
"maxResult": 20, "allNum": 10, "allPages": 1, "currentPage": 1
}
}
```
| 字段 | 含义 |
|------|------|
| `province/city/area/county` | 省/市/区县/街道 |
| `code` | 邮编（字符串） |
| `areacode` | 电话区号（未文档化，实测稳定返回） |
## 进阶/边界
- **一对多**：一个邮编对应多个 `county`，用 `page` 翻页；`allNum`/`allPages` 告诉你总量。
- **地址校验**：可把用户输入的省/市/区与返回结果比对，不一致则提示用户核对。
- **缓存**：邮编→地区相对稳定，建议本地缓存（见《缓存策略》）。
- **边界**：邮编须为 6 位有效数字；查不到时 `ret_code` 非 0，看 `msg`。
## FAQ
**Q1：一个邮编返回多条街道正常吗？**
正常，区县级下有多个街道/乡镇，翻页取全。
**Q2：返回里有区号 `areacode` 吗？**
有，实测稳定返回（如 0595），文档未单列。
**Q3：邮编输错几位会怎样？**
可能 `ret_code` 非 0 或无结果，按 `msg` 处理。
**Q4：`maxResult` 是多少？**
每页最大 20 条，由接口固定返回。
**Q5：能只查省一级吗？**
接入点1 以邮编为入口，最小粒度到街道；按省聚合需自己处理返回。
## 相关能力 / 下一步阅读
- [邮编区域互查返回字段全解](https://www.showapi.com/guides/postcode-response-fields-1917)
- [免费接口如何设计缓存策略](https://www.showapi.com/guides/postcode-cache-1917)
- [邮编区域互查错误码排查](https://www.showapi.com/guides/postcode-error-codes-1917)
- **本系列共 12 篇**：查看[邮编区域互查指南总目录](https://www.showapi.com/guides/postcode-guides-1917)
