手机归属地查询：导入 Apifox/Postman，用 OpenAPI 文档管理接口
手机归属地查询OpenAPIApifoxPostman # 手机归属地查询：导入 Apifox/Postman，用 OpenAPI 文档管理接口
> **接口**：手机归属地查询 `6-1` ｜ **是否免费**：是（注册默认可免费调用，有使用档次限制）｜ **请求方式**：POST / GET ｜ **返回格式**：JSON ｜ **适用人群**：API 治理团队、后端/测试负责人、需要统一维护接口文档的团队 ｜ **阅读时间**：约 6 分钟
## TL;DR
- 易源为手机归属地查询（apiCode=6）提供了官方 **OpenAPI 3.0 文档**，有 YAML 和 JSON 两种格式，覆盖全部接入点。
- 把文档导入 Apifox / Postman，能**自动生成请求模板、参数说明和 Mock**，不用手敲 URL 和字段。
- 适合"一个接口要被多个团队用、还得有统一文档和测试环境"的治理场景；OpenAPI 还能进一步生成 SDK 和多语言文档。
## Why：为什么治理团队该用 OpenAPI？
当接口只你一个人用，写段代码跑通就行。但一旦它要面向多个团队——前端要对接、测试要造用例、其他同事要自查——"口口相传的 URL 和参数"就撑不住了：字段含义记错、必填漏传、返回结构对不上，问题频发。
OpenAPI 是接口的描述标准。易源把手机归属地接口的描述写成了一份 OpenAPI 3.0 文档，你导入 Apifox / Postman 后，工具会**照着文档把请求面板、参数表、响应结构全部画出来**，还能一键 Mock。对治理团队来说，这份文档就是"接口的事实来源（Single Source of Truth）"：改一版、全团队同步，不用各自维护一份野文档。
## What：OpenAPI 资源速览
| 项目 | 内容 |
|------|------|
| 产品 | 手机归属地查询（apiCode=6） |
| 接入点 | `6-1`（本接口仅 1 个接入点，同步请求-响应） |
| OpenAPI 3.0（YAML） | `https://www.showapi.com/openapi/market/6.yaml` |
| OpenAPI 3.0（JSON） | `https://www.showapi.com/openapi/market/6.json` |
| 覆盖范围 | **全部接入点**（当前手机归属地仅 `6-1`） |
| 接口地址 | `https://route.showapi.com/6-1?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 必填参数 | `num`（手机号，字符串） |
| 返回格式 | JSON，业务数据在 `showapi_res_body` 内 |
| 计费 | 免费服务（注册默认可免费调用，设使用档次限制）；失败不扣点数 |
> 文档描述的是同一个接口，事实底座与 [《5 分钟接入》](https://www.showapi.com/guides/phone-attribution-quickstart-6) 完全一致；OpenAPI 只是把这些信息标准化了。
## How：下载并导入 OpenAPI 文档
### 步骤 1 · 下载 OpenAPI 文档
直接访问下面两个地址之一，保存文件到本地：
- YAML：`https://www.showapi.com/openapi/market/6.yaml`
- JSON：`https://www.showapi.com/openapi/market/6.json`
两者内容等价，按你工具偏好选（Apifox / Postman 都支持）。下面以 YAML 为例。
### 步骤 2 · 导入 Apifox
1. 打开 Apifox，新建或进入一个项目。
2. 点击 `项目设置 → 导入` 或左上角 `导入` 按钮，选择 `OpenAPI / Swagger` 类型。
3. 选择刚下载的 `6.yaml`，确认导入。
4. 导入完成后，左侧会出现手机归属地查询接口（`6-1`），点开即可看到自动生成的：
- 请求地址 `https://route.showapi.com/6-1`
- 参数面板（`appKey` 路径/查询参数、`num` 必填参数）
- 响应结构（`showapi_res_body` 及全部字段）
5. 在 `appKey` / `num` 里填入你的值（AppKey 来自 [AppKey 管理页](https://www.showapi.com/console#/myApp)），即可发送请求。
### 步骤 3 · 导入 Postman
1. 打开 Postman，点击 `Import`。
2. 拖入 `6.yaml` / `6.json`，或粘贴文件内容 / URL。
3. Postman 会生成对应的 Collection，包含接口、参数与环境变量占位。
4. 在变量里设置 `appKey`（你的真实 AppKey），即可调用。
### 步骤 4 · 开启 Mock（可选）
Apifox / Postman 都能基于 OpenAPI 的响应结构自动生成 Mock 服务。开启后，前端/测试可以在"还没接真实接口"时用 Mock 地址拿到结构化返回，做联调与回归，不必等你把真实环境准备好。
### 步骤 5 · 用 OpenAPI 生成 SDK / 文档（进阶）
OpenAPI 是标准描述，生态里有大量代码生成器（如 OpenAPI Generator）。你可以基于 `6.yaml` 生成多种语言的 SDK 或多语言接口文档，把"易源这份官方描述"直接变成团队内的调用骨架。具体命令取决于你选用的生成器，**本文只说明可行性与入口，不限定某一种工具**。
## 返回示例与解析
无论经代码、MCP 还是 OpenAPI 工具调用，底层返回都是同一个结构。`18908711111` 的真实返回如下：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"num": 1890871,
"prov": "云南",
"ret_code": 0,
"areaCode": "0871",
"name": "电信",
"cityCode": "530100",
"postCode": "650000",
"provCode": "530000",
"type": 2,
"city": "昆明"
}
}
```
| 字段 | 含义 | 本例值 |
|------|------|--------|
| `prov` | 省 | 云南 |
| `city` | 市 | 昆明 |
| `name` | 运营商名称 | 电信 |
| `num` | 号段（前 7 位，Number） | 1890871 |
| `type` | 运营商枚举（1移动/2电信/3联通/4广电/-1未知） | 2 |
| `areaCode` | 城市区号 | 0871 |
| `postCode` | 邮政编码（来源：返回示例/产品说明） | 650000 |
| `provCode` | 省别编码（本省身份证前几位） | 530000 |
| `cityCode` | 城市编码（本城市身份证前几位） | 530100 |
| `ret_code` | 业务状态码，0 成功，其他失败 | 0 |
> 字段完整定义与类型见 [《手机归属地返回字段全解》](https://www.showapi.com/guides/phone-attribution-response-fields-6)。
## 进阶 / 边界
- **OpenAPI 覆盖全部接入点**：当前手机归属地仅 `6-1` 一个接入点，文档已涵盖；若官方新增接入点，以官方最新 OpenAPI 文档为准。
- **失败不扣点数**：`ret_code != 0`（如 `-2` 非 11 位、`-3` 含非数字、`-4` 格式错、`-5/-6` 找不到归属地）时不消耗额度。测试/造用例时可放心用错误号码演练。
- **免费档位限制**：OpenAPI 调用走的是同一接口、同一档位额度，Mock 不消耗真实调用，但发真实请求会计入免费档次用量。
- **文档内部不一致的处理**：`areaCode` 参数表写 `0810`、返回示例写 `0871`（昆明真实区号 `0871`），以 `0871` 为准；`postCode` 参数表未登记但返回示例与产品说明有，列为真实字段并标注来源。这些不影响 OpenAPI 导入使用，返回以官方实际值为准。
## FAQ
**Q1：YAML 和 JSON 哪个更好？导入有区别吗？**
内容等价，Apifox / Postman 都支持。习惯读文本选 YAML，习惯机器处理选 JSON，按团队偏好即可。
**Q2：OpenAPI 文档里有我的 AppKey 吗？**
没有。文档是接口"描述"，AppKey 是你调用时自己填的鉴权参数，来自 [AppKey 管理页](https://www.showapi.com/console#/myApp)，不要写进共享的 OpenAPI 文件里。
**Q3：导入后为什么参数和我手写的对不上？**
以官方 OpenAPI 文档为准：必填参数只有 `num`，鉴权走 `appKey`。若你之前的脚本多传了字段，那多半是冗余参数，按文档精简即可。
**Q4：Mock 返回的是真实数据吗？**
不是。Mock 是按响应结构生成的占位数据，用于联调与前端开发；真实归属地必须发真实请求到 `6-1` 接入点。
**Q5：能用 OpenAPI 直接生成客户端代码吗？**
可以。OpenAPI 生态有大量生成器，可基于 `6.yaml` 生成多语言 SDK/文档。本文不绑定具体工具，只说明"官方描述可复用为标准生成入口"。
**Q6：调用失败会扣点数吗？**
不会。失败（`ret_code!=0`）不扣点数，成功调用计入免费档位用量。
## 相关能力 / 下一步阅读
- [《5 分钟接入手机归属地查询：从注册到第一条返回》](https://www.showapi.com/guides/phone-attribution-quickstart-6) —— 最快跑通路径，先拿到第一条真实返回
- [《通过 MCP 在 AI 客户端直接查手机号归属地》](https://www.showapi.com/guides/phone-attribution-mcp-6) —— 把接口变成 AI 可调用工具的另一种集成方式
- [《手机归属地返回字段全解：prov/city/type/postCode 一文读懂》](https://www.showapi.com/guides/phone-attribution-response-fields-6) —— 每个字段的类型、取值与坑位
- **本系列共 12 篇**：查看[手机归属地查询 · 官方指南总目录](https://www.showapi.com/guides/phone-attribution-guides-6)
