邮编区域互查指南总目录

# 邮编区域互查指南总目录 > 邮编区域互查（apiCode=1917）是 ShowAPI 生活服务类下的**免费接口**，由易源（万维易源，昆明秀派科技有限公司）官方自营。它支持「邮编查地区」与「地区查邮编」双向互查，适用于快递物流、地址验证、地图服务、在线购物、数据分析等场景。本文汇总全系列指南，帮助你按自己的角色和阶段快速找到对应文章。 ## 接口一句话速览 - **三个接入点**：① `1917-1` 邮编查询区域（邮编→地区）② `1917-2` 地区查询邮编（地区→邮编）③ `1917-3` 查询详细地区的邮编（省/市/区/街道→邮编）。 - **请求方式**：POST / GET 均支持，返回 JSON。 - **鉴权**：AppKey 放 query 参数 `appKey`，密钥在「我的 AppKey」管理。 - **计费**：免费接口，注册后默认可免费调用，有使用档次限制；可用平台积分兑换更高档位。 - **集成能力**：提供 MCP 服务与 OpenAPI 3.0 文档，覆盖全部接入点。 ## 全系列文章（共 12 篇） ### 入门层 1. [邮编区域互查：5 分钟接入，从注册到第一条查询结果](https://www.showapi.com/guides/postcode-quickstart-1917) — 注册、取 AppKey、首次调用、解析返回的最小闭环。 2. [邮编区域互查返回字段全解：area/county/city/province/code(postcode)/areacode 一文读懂](https://www.showapi.com/guides/postcode-response-fields-1917) — 系统级与业务级字段对照，含 `postcode` 与未文档化 `areacode` 修正。 3. [邮编区域互查错误码排查：ret_code=0/-1 与“没有找到相关区域信息”](https://www.showapi.com/guides/postcode-error-codes-1917) — 两层返回码与失败排查决策树。 ### 场景实战层 4. [邮编区域互查·邮编查地区（接入点1）实战：快递物流与地址验证怎么用](https://www.showapi.com/guides/postcode-zip-to-region-1917) — 传入 6 位邮编补全省市区街道与区号。 5. [邮编区域互查·地区查邮编（接入点2）实战：为什么传“昆明”返回 -1、要传区/县](https://www.showapi.com/guides/postcode-region-to-zip-1917) — 实测踩坑：`area` 须传区/县级，返回字段为 `postcode`。 6. [邮编区域互查·查询详细地区邮编（接入点3）实战：省市区三级联动查询](https://www.showapi.com/guides/postcode-detail-query-1917) — 省/市/区/街道逐级筛选（如实标注免费档位实测差异）。 7. [邮编区域互查 + 地图标点：把省市区数据落到地图上](https://www.showapi.com/guides/postcode-map-visualization-1917) — 取回行政区划后结合外部地理编码标点。 ### 技术深挖层 8. [邮编区域互查里的 areacode 电话区号字段：顺带拿到区号怎么用](https://www.showapi.com/guides/postcode-areacode-field-1917) — 未文档化字段 `areacode` 的验证与用法。 9. [邮编区域互查分页与 maxResult/allNum 实战：大结果集怎么翻页](https://www.showapi.com/guides/postcode-pagination-1917) — `page`/`maxResult`/`allNum`/`allPages` 用法。 10. [免费接口如何设计缓存策略：邮编→地区映射本地化省调用](https://www.showapi.com/guides/postcode-cache-1917) — 相对稳定数据本地缓存，减少调用。 ### 生态集成层 11. [通过 MCP 协议在 AI 客户端（Cherry Studio/ChatBox）直接查邮编](https://www.showapi.com/guides/postcode-mcp-1917) — 基于官方 MCP 配置在 AI 客户端直接调用。 12. [导入 Postman / Swagger UI：用 OpenAPI 文档管理邮编区域互查接口](https://www.showapi.com/guides/postcode-openapi-1917) — 下载 YAML 导入 API 工具管理接口。 ## 相关资源 | 资源 | 链接 | |------|------| | 接口详情页 | https://www.showapi.com/apiGateway/view/1917 | | 接入点1（邮编查地区） | https://www.showapi.com/apiGateway/view/1917/1 | | 接入点2（地区查邮编） | https://www.showapi.com/apiGateway/view/1917/2 | | 接入点3（详细地区邮编） | https://www.showapi.com/apiGateway/view/1917/3 | | OpenAPI 文档（YAML） | https://www.showapi.com/openapi/market/1917.yaml | | OpenAPI 文档（JSON） | https://www.showapi.com/openapi/market/1917.json | | AppKey 管理 | https://www.showapi.com/console#/myApp | | 免费接口档位说明 | https://www.showapi.com/free-api | ## 阅读建议 - **第一次用**：从《5 分钟接入》开始，跑通第一条查询。 - **写代码前**：看《返回字段全解》和《错误码排查》，避免把 `postcode` 误当 `code`、把市级名传给接入点2。 - **做系统**：接《分页》《缓存》《地图标点》三篇做生产级设计。 - **用 AI 客户端**：直接看《MCP 集成》与《OpenAPI 导入》。 > 本系列由真实接口调用实测校验，所有字段名、边界与实测差异均以官方文档与真实返回为准，不臆造参数或量化数据。