邮编区域互查：5 分钟接入，从注册到第一条查询结果
邮编查询邮编区域互查ShowAPI免费接口API教程 # 邮编区域互查：5 分钟接入，从注册到第一条查询结果
> 邮编区域互查（apiCode=1917）· 免费接口 · POST/GET · JSON · 新注册用户/初级开发者 · 约 6 分钟
## 核心要点
- 邮编区域互查是免费接口，注册 ShowAPI 账号、拿到 AppKey 即可调用，无付费门槛。
- 一条请求 = 接口地址 + `appKey` + 业务参数（如邮编 `code`），返回 JSON 业务数据。
- 实测 5 分钟可跑通：用接入点1 传 `code=362504`（德化县）即可拿到省市区街道与电话区号。
## Why：这跟我有什么关系
做电商、快递、表单地址校验、地图标点时，经常只有「邮编」或只有「地区名」，需要互查补全。这个接口把这件事做成了一个 HTTP 调用——不用自己维护邮编库，也不用担心数据过期。免费、官方自营、稳定，是地址类需求的最低成本起点。
## What：前置条件与接口速览
| 项 | 说明 |
|----|------|
| 接口 | 邮编区域互查（apiCode=1917），3 个接入点 |
| 接入点1 地址 | `https://route.showapi.com/1917-1?appKey={your_appKey}` |
| 请求方式 | POST / GET |
| 鉴权 | query 参数 `appKey` |
| 计费 | 免费（注册后默认免费调用，有使用档次限制） |
| 更新频率 | 数据持续更新，每次返回最新数据 |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档（覆盖全部接入点） |
前置条件：① 注册 ShowAPI 账号；② 在「我的 AppKey」创建一个应用拿到 `appKey`；③ 本机有网络与任意 HTTP 客户端（Python/cURL/Node 均可）。
## How：第一次调用（接入点1，邮编查地区）
下面以「邮编 `362504` 查地区」为例，三种语言任选其一，替换 `YOUR_APPKEY` 即可运行。
### Python（requests）
```python
import requests
APP_KEY = "YOUR_APPKEY"
url = "https://route.showapi.com/1917-1"
params = {"appKey": APP_KEY, "code": "362504", "page": "1"}
try:
r = requests.post(url, params=params, timeout=10)
r.raise_for_status()
data = r.json()
except Exception as e:
print("请求失败:", e)
raise
body = data.get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("业务失败:", body.get("msg"))
else:
for item in body.get("contentlist", []):
print(item.get("province"), item.get("city"),
item.get("area"), item.get("county"),
"邮编", item.get("code"), "区号", item.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 APP_KEY = "YOUR_APPKEY";
const url = `https://route.showapi.com/1917-1?appKey=${APP_KEY}`;
const body = new URLSearchParams({ code: "362504", page: "1" });
const res = await fetch(url, { method: "POST", body, signal: AbortSignal.timeout(10000) });
const data = await res.json();
const b = data.showapi_res_body;
if (b.ret_code !== 0) { console.log("业务失败:", b.msg); }
else { console.log(b.contentlist); }
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"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
}
}
```
| 字段 | 含义 |
|------|------|
| `showapi_res_code` | 系统级状态码，0 为成功 |
| `showapi_res_body.ret_code` | 业务码，0 成功、-1 失败 |
| `contentlist[].province/city/area/county` | 省 / 市 / 区县 / 街道 |
| `contentlist[].code` | 邮编（接入点1 字段名为 `code`） |
| `contentlist[].areacode` | 电话区号（如 0595），文档未单列但实测稳定返回 |
> 注意：接入点2 返回的邮编字段名是 `postcode`（不是 `code`），详见《返回字段全解》。
## 进阶/边界
- 免费接口有使用档次限制，高频调用建议看《缓存策略》一文做本地缓存。
- 一个邮编可能对应多个街道（如 `362504` 对应多个 `county`），用 `page` 翻页取全。
- 接入点2 的 `area` 要传**区/县级**名称（如「官渡区」），传市级（如「昆明」）会返回 `-1`，详见《地区查邮编实战》。
## FAQ
**Q1：需要付费吗？**
不需要。这是免费接口，注册后默认可调用，仅有使用档次（频次）限制。
**Q2：AppKey 在哪拿？**
登录后在「我的 AppKey」创建应用即可获取。
**Q3：返回里 `areacode` 是什么？**
电话区号（如 0595 代表泉州），文档参数表未单列，但实测三个接入点都会返回。
**Q4：为什么我传邮编返回空？**
邮编需为 6 位有效数字；若确实查不到，业务 `ret_code` 会非 0，检查 `msg`。
**Q5：POST 和 GET 哪个好？**
都能用；参数少时 GET 更直观，参数多或含特殊字符时建议 POST。
**Q6：一个邮编有多条结果怎么办？**
用 `page` 参数翻页，`allNum`/`allPages` 告诉你总量与页数。
## 相关能力 / 下一步阅读
- [邮编区域互查返回字段全解](https://www.showapi.com/guides/postcode-response-fields-1917)
- [邮编区域互查错误码排查](https://www.showapi.com/guides/postcode-error-codes-1917)
- [邮编区域互查·邮编查地区（接入点1）实战](https://www.showapi.com/guides/postcode-zip-to-region-1917)
- **本系列共 12 篇**：查看[邮编区域互查指南总目录](https://www.showapi.com/guides/postcode-guides-1917)
