邮编区域互查返回字段全解：area/county/city/province/code(postcode)/areacode 一文读懂

# 邮编区域互查返回字段全解：area/county/city/province/code(postcode)/areacode 一文读懂 > 邮编区域互查（apiCode=1917）· 免费接口 · POST/GET · JSON · 初级~中级开发者 · 约 8 分钟 ## 核心要点 - 返回分两层：系统级（`showapi_res_code` 等）包裹业务级 `showapi_res_body`，业务数据都在 `showapi_res_body` 里。 - 三个接入点的 `contentlist` 结构大体一致，但**邮编字段名不同**：接入点1/3 叫 `code`，接入点2 叫 `postcode`——文档参数表把接入点2 错写成 `code`，本文以实测为准。 - 三个接入点实测都会返回文档未单列的 `areacode`（电话区号），可一并利用。 ## Why：读懂字段才能写对代码 字段名写错是接入这个接口最常见的坑：把接入点2 的 `postcode` 当成 `code` 去取，结果拿到 `undefined`。本文把三个接入点的字段一次性讲清，并标出文档与实测的差异，省去你踩坑返工。 ## What：前置条件与接口速览 | 项 | 说明 | |----|------| | 接口 | 邮编区域互查（apiCode=1917） | | 接入点 | 1917-1 邮编查地区 / 1917-2 地区查邮编 / 1917-3 详细地区邮编 | | 返回格式 | JSON，业务数据在 `showapi_res_body` | | 计费 | 免费（有使用档次限制） | ## How：两层返回结构与字段表 ### 系统级字段（每次都在最外层） | 字段 | 类型 | 说明 | |------|------|------| | `showapi_res_code` | Number | 系统级状态码，0 为成功 | | `showapi_res_error` | String | 错误信息，成功时为空 | | `showapi_res_id` | String | 本次请求标识 | | `showapi_fee_num` | Number | 本次计费条数（免费接口也返回） | | `showapi_res_body` | Object | 业务数据容器 | ### 业务级 `showapi_res_body` 公共字段 | 字段 | 类型 | 说明 | |------|------|------| | `ret_code` | Number | 业务码：0 成功，-1 失败（如查不到地区） | | `msg` | String | 返回说明，如「查询成功！」「抱歉，没有找到相关的区域信息！」 | | `contentlist` | Array | 结果列表；失败或未命中时可能为空/不返回 | | `currentPage` / `allPages` / `allNum` / `maxResult` | Number | 分页信息（见《分页实战》） | ### `contentlist[]` 逐接入点字段对照 | 字段 | 1917-1 邮编查地区 | 1917-2 地区查邮编 | 1917-3 详细地区邮编 | 说明 | |------|------|------|------|------| | `province` | ✅ | ✅ | ✅ | 省 | | `city` | ✅ | ✅ | ✅ | 城市 | | `area` | ✅ | ✅ | ✅ | 区县 | | `county` | ✅ | ✅ | ✅ | 街道/乡镇 | | **邮编字段** | `code` | **`postcode`** | `code` | ⚠️ 接入点2 是 `postcode`，非文档参数表所写 `code` | | `areacode` | ✅（未文档化） | ✅（未文档化） | ✅（未文档化） | 电话区号，如 0595/0871 | | `_id` / `update` / `ct` | — | ✅ | — | 接入点2 额外元数据 | ## 返回示例（接入点2，地区查邮编，实测） ```json { "showapi_res_code": 0, "showapi_fee_num": 1, "showapi_res_body": { "ret_code": 0, "msg": "查询成功！", "contentlist": [ {"_id":"62f574a6d08520548a967210","area":"官渡区","county":"七家村","city":"昆明市","province":"云南省","postcode":"650217","areacode":"0871"} ] } } ``` 注意：这里邮编是 **`postcode`**，取值应写 `item.postcode`，不是 `item.code`。 ## 进阶/边界 - **不要混用字段名**：接入点2 用 `postcode`，其余用 `code`。统一封装一层映射函数最稳。 - **`areacode` 未文档化但稳定**：可作为「顺带拿到电话区号」的红利，详见《areacode 字段深挖》。 - **失败结构更精简**：接入点2 查不到时只返回 `ret_code`+`msg`，无 `contentlist`，取数前务必判空。 - **文档差异已如实标注**：本文所有字段名均经真实调用校验，与文档冲突处以上文为准。 ## FAQ **Q1：为什么接入点2 取不到邮编？** 因为它返回的是 `postcode` 字段，不是 `code`；文档参数表写错了，以实测为准。 **Q2：`areacode` 文档没写，能信吗？** 三个接入点实测均稳定返回，可放心使用，但因其未在官方参数表列出，建议以实际返回为准并做兜底。 **Q3：`ret_code` 和 `showapi_res_code` 有什么区别？** 前者是业务结果（查到/没查到），后者是系统级（请求是否成功送达）；都要判 0。 **Q4：失败时会返回 `contentlist` 吗？** 接入点2 查不到时不返回，直接用会报错，先判 `ret_code`。 **Q5：邮编字段类型是什么？** 字符串（如 `"362504"`），比较时注意不要当成数字。 ## 相关能力 / 下一步阅读 - [邮编区域互查错误码排查](https://www.showapi.com/guides/postcode-error-codes-1917) - [邮编区域互查·地区查邮编（接入点2）实战](https://www.showapi.com/guides/postcode-region-to-zip-1917) - [邮编区域互查里的 areacode 电话区号字段](https://www.showapi.com/guides/postcode-areacode-field-1917) - **本系列共 12 篇**：查看[邮编区域互查指南总目录](https://www.showapi.com/guides/postcode-guides-1917)