邮编区域互查·地区查邮编（接入点2）实战：为什么传“昆明”返回 -1、要传区/县
邮编查询邮编区域互查ShowAPI免费接口API教程 # 邮编区域互查·地区查邮编（接入点2）实战：为什么传“昆明”返回 -1、要传区/县
> 邮编区域互查（apiCode=1917）· 接入点2 地区查询邮编 · 免费接口 · 初级~中级开发者 · 约 8 分钟
## 核心要点
- 接入点2（`1917-2`）是「地区 → 邮编」：传 `area`，返回邮编。
- ⚠️ **返回字段名是 `postcode`，不是文档参数表写的 `code`**——以实测为准。
- ⚠️ **`area` 必须传区/县级名称**（如「官渡区」）。传市级（「昆明」「上海市」）实测返回 `ret_code:-1 "没有找到相关的区域信息！"`。
- 失败时无 `contentlist`，取数前务必判空。
## Why：这是踩坑最多的一个接入点
接入点2 有两处和直觉/文档不一致：字段名是 `postcode` 而非 `code`，且 `area` 只认区/县级。直接用文档参数表写 `item.code` 或传城市名，就会拿不到数据。本文用实测把这两点钉死。
## What：接口速览
| 项 | 说明 |
|----|------|
| 接入点地址 | `https://route.showapi.com/1917-2?appKey={your_appKey}` |
| 请求参数 | `area`（地区，非必填）、`page`（页码，非必填） |
| 返回邮编字段名 | **`postcode`** |
| 计费 | 免费（有使用档次限制） |
## How：地区查邮编（正确写法）
### Python
```python
import requests
def region_to_zip(app_key, area, page=1):
r = requests.post("https://route.showapi.com/1917-2",
params={"appKey": app_key, "area": area, "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") # 如 area 传市级名会到这里
return body.get("contentlist", []), None
# 正确：传区/县级
items, err = region_to_zip("YOUR_APPKEY", "官渡区")
if err:
print("失败:", err)
else:
for it in items:
print(it["province"], it["city"], it["area"], "邮编", it["postcode"], "区号", it.get("areacode"))
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1917-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "area=官渡区" --data-urlencode "page=1"
```
### Node.js（fetch）
```javascript
const res = await fetch(`https://route.showapi.com/1917-2?appKey=YOUR_APPKEY`,
{ method: "POST", body: new URLSearchParams({ area: "官渡区", 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); // 取 it.postcode，不是 it.code
```
## 返回示例与解析（实测）
```json
{
"showapi_res_body": {
"ret_code": 0, "msg": "查询成功！",
"contentlist": [
{"_id":"62f574a6d08520548a967210","area":"官渡区","county":"七家村","city":"昆明市","province":"云南省","postcode":"650217","areacode":"0871"}
]
}
}
```
| 字段 | 说明 |
|------|------|
| `postcode` | 邮编（⚠️ 注意是 `postcode`，不是 `code`） |
| `province/city/area/county` | 省/市/区县/街道 |
| `areacode` | 电话区号（未文档化，实测稳定返回） |
## 进阶/边界
- **`area` 取值**：传区/县级（如「官渡区」「西山区」），不要传市级（「昆明」「上海市」会 -1）。个别区/县可能不在免费档位数据集内，返回 -1 属正常。
- **字段名映射**：建议在代码里统一把 `postcode` 映射成你的「邮编」字段，避免和接入点1/3 的 `code` 混用。
- **失败结构精简**：查不到时只有 `ret_code`+`msg`，无 `contentlist`。
- **文档差异已标注**：参数表写 `code` 有误，本文以实测 `postcode` 为准。
## FAQ
**Q1：为什么我传「昆明」返回 -1？**
`area` 要传区/县级名称，市级名不在匹配范围，会返回「没有找到相关的区域信息」。
**Q2：邮编字段到底叫什么？**
接入点2 实测叫 `postcode`；文档参数表误写为 `code`，以本文为准。
**Q3：传区名还是县名？**
区或县都可以，只要是区/县级行政名，而非市级。
**Q4：返回里有没有区号？**
有 `areacode`（如 0871），实测稳定返回。
**Q5：失败时有 `contentlist` 吗？**
没有，取数前先判 `ret_code`。
## 相关能力 / 下一步阅读
- [邮编区域互查返回字段全解](https://www.showapi.com/guides/postcode-response-fields-1917)
- [邮编区域互查错误码排查](https://www.showapi.com/guides/postcode-error-codes-1917)
- [邮编区域互查里的 areacode 电话区号字段](https://www.showapi.com/guides/postcode-areacode-field-1917)
- **本系列共 12 篇**：查看[邮编区域互查指南总目录](https://www.showapi.com/guides/postcode-guides-1917)
