# 手机归属地查询 · 官方指南总目录
> **接口**：手机归属地查询 `6-1` ｜ **分类**：交通地理 ｜ **服务商**：昆明秀派科技有限公司（易源官方自营） ｜ **是否免费**：是（注册默认可免费调用，设使用档次限制） ｜ **请求方式**：POST / GET ｜ **返回格式**：JSON
这是**手机归属地查询**（易源 ShowAPI，apiCode=6）的官方指南系列总目录。本接口只需传入一个手机号 `num`，即可返回省、市、运营商名称、号段、区号、邮编、省/市编码等信息；免费服务，注册后默认可调用（设使用档次限制），失败时（`ret_code!=0`）不扣点数。
全系列共 **12 篇**，按「入门 → 技术 → 生态 → 行业」分层组织。下面先给接口一句话速览，再分层列出全部文章（含每篇的"什么时候看"提示），随后是字段速查、错误码速查、文档不一致口径、最小代码入口、相关资源表与阅读建议，最后附 FAQ。
## 接口一句话速览
| 项目 | 内容 |
|------|------|
| 产品名 | 手机归属地查询 |
| 分类 | 交通地理 |
| 服务商 | 昆明秀派科技有限公司（易源官方自营） |
| 接入点 | `6-1`（仅 1 个接入点，同步请求-响应；无订阅推送、无回调、无官方批量能力） |
| 接口地址 | `https://route.showapi.com/6-1?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 必填参数 | 仅 `num`（String，手机号，示例 `18908711111`） |
| 返回格式 | JSON，业务数据全部在 `showapi_res_body` 内（扁平 Object，10 个标量字段） |
| 返回字段 | `prov` / `city` / `name` / `num` / `provCode` / `cityCode` / `areaCode` / `type` / `ret_code` / `postCode` |
| 运营商枚举 `type` | 1=移动、2=电信、3=联通、4=广电、-1=未知 |
| 错误码 `ret_code` | -2=不是11位、-3=含非数字字符、-4=格式错误、-5/-6=找不到归属地；0=成功 |
| 更新频率 | 半年更新一次新号段归属地 |
| 计费 | 免费服务（设使用档次限制）；失败不扣点数 |
| 集成能力 | MCP 服务、OpenAPI 3.0（YAML / JSON） |
| 能力边界 | 不支持携号转网查询；无官方批量能力 |
## 全系列文章（12 篇）
### 一、入门篇（先跑通，再深入）
1. **[手机归属地查询：5 分钟接入，从注册到第一条返回](https://www.showapi.com/guides/phone-attribution-quickstart-6)**
- 一句话：注册拿 AppKey → 发请求 → 解析 `showapi_res_body` 的最短路径，含 Python / cURL / Node.js 可运行代码。
- 看这篇当：你刚拿到 AppKey，想 5 分钟内拿到第一条真实返回。
2. **[手机归属地查询返回字段全解：prov/city/type/postCode 一文读懂](https://www.showapi.com/guides/phone-attribution-response-fields-6)**
- 一句话：逐个拆解 `showapi_res_body` 内 10 个字段的类型、取值与坑位，含文档内部不一致的处理说明。
- 看这篇当：你要把返回字段一一映射进自己的数据库/结构体，怕记错类型或取值。
3. **[手机归属地查询错误码排查：-2 非11位 / -3 非数字 / -4 格式 / -5-6 找不到](https://www.showapi.com/guides/phone-attribution-error-codes-6)**
- 一句话：`ret_code` 负数全集对照与排查路径，配客户端校验建议，减少无效调用。
- 看这篇当：你遇到查询失败，想快速定位是号码格式问题还是真找不到归属地。
### 二、技术集成篇（把接口接进你的系统）
4. **[手机归属地查询：注册/表单防错，用手机号归属地做实时校验与运营商识别](https://www.showapi.com/guides/phone-attribution-form-validation-6)**
- 一句话：在注册/表单场景做实时归属地校验与运营商识别，拦截明显错误号码。
- 看这篇当：你在做注册/开户表单，想顺手校验号码并识别运营商。
5. **[手机归属地查询：Excel 批量查归属地，用脚本替代手工逐条查](https://www.showapi.com/guides/phone-attribution-excel-batch-6)**
- 一句话：用脚本读取号码清单、逐条查询并回填，替代手工逐条查（注意接口无官方批量能力）。
- 看这篇当：你有一张号码表要补归属地，不想一条条手查。
6. **[手机归属地查询 type 字段全解：1移动/2电信/3联通/4广电/-1未知怎么用](https://www.showapi.com/guides/phone-attribution-type-field-6)**
- 一句话：运营商枚举字段的完整用法：识别、分支逻辑、未知值（-1）如何兜底。
- 看这篇当：你的业务逻辑要根据运营商走不同分支（如短信通道选择）。
7. **[手机归属地查询：免费档位下如何做缓存，本地缓存手机号→归属地减少调用](https://www.showapi.com/guides/phone-attribution-cache-6)**
- 一句话：在免费档位限制下，用本地缓存手机号→归属地映射，降低调用量、避开额度上限。
- 看这篇当：你频繁查同一批号码，想把免费档位用在刀刃上。
### 三、生态 / 工具篇（用现代工具链管理接口）
8. **[手机归属地查询：通过 MCP 在 AI 客户端直接查手机号归属地](https://www.showapi.com/guides/phone-attribution-mcp-6)**
- 一句话：在 Cherry Studio / ChatBox 等支持 MCP 的客户端配置 `showapi-mcp-6`，用自然语言对话式查询。
- 看这篇当：你想在 AI 对话里直接说"查一下 18908711111 是哪里的"。
9. **[手机归属地查询：导入 Apifox/Postman，用 OpenAPI 文档管理接口](https://www.showapi.com/guides/phone-attribution-openapi-6)**
- 一句话：下载官方 OpenAPI 3.0 文档，导入 Apifox / Postman 自动生成请求模板与 Mock，适合 API 治理。
- 看这篇当：你是 API 治理/测试负责人，需要一个统一、可 Mock 的接口描述。
### 四、业务场景篇（按角色找用法）
10. **[手机归属地查询：CRM/客服系统接入，来电即显示归属地与运营商](https://www.showapi.com/guides/phone-attribution-crm-6)**
- 一句话：来电弹屏场景：号码一进，立刻展示省/市/运营商，提升客服效率。
- 看这篇当：你在做客服/CRM 系统，想来电即弹归属地。
11. **[手机归属地查询：电商风控，用归属地识别异常下单与区域分布](https://www.showapi.com/guides/phone-attribution-ecommerce-6)**
- 一句话：用归属地识别异常下单模式、分析订单区域分布，辅助风控决策。
- 看这篇当：你在做电商，想用归属地做风控特征或区域分析。
12. **[手机归属地查询：物流/外卖场景，收货号码归属地校验与派送分区](https://www.showapi.com/guides/phone-attribution-logistics-6)**
- 一句话：校验收货号码归属地、辅助派送分区与异常地址识别。
- 看这篇当：你在做物流/外卖，想校验收货号码并辅助分区。
## 返回字段速查
以下是 `showapi_res_body` 内 10 个字段的完整速查（以 `18908711111` 真实返回为例）：
| 字段 | 类型 | 含义 | 示例值 | 备注 |
|------|------|------|--------|------|
| `prov` | String | 省 | 云南 | — |
| `city` | String | 市 | 昆明 | 粒度到"市"，不到区/县 |
| `name` | String | 运营商名称 | 电信 | 与 `type` 对应 |
| `num` | Number | 号段（前 7 位） | 1890871 | 不是完整手机号 |
| `provCode` | Number | 省别编码（本省身份证前几位） | 530000 | — |
| `cityCode` | Number | 城市编码（本城市身份证前几位） | 530100 | — |
| `areaCode` | String | 城市区号 | 0871 | 以官方实际返回为准（见"文档不一致口径"） |
| `type` | Number | 运营商枚举 | 2 | 1移动/2电信/3联通/4广电/-1未知 |
| `ret_code` | Number | 业务状态码 | 0 | 0 成功，负数失败 |
| `postCode` | String | 邮政编码 | 650000 | 来源：返回示例/产品说明（参数表未登记） |
> 完整逐字段解读见 [《手机归属地查询返回字段全解》](https://www.showapi.com/guides/phone-attribution-response-fields-6)。
## 错误码速查
`ret_code` 为负数表示失败（`ret_code != 0` 时不扣点数）：
| 错误码 | 含义 | 排查建议 |
|--------|------|----------|
| `-2` | 不是 11 位 | 检查号码长度，应为 11 位 |
| `-3` | 含非数字字符 | 移除空格、+86、连字符等 |
| `-4` | 格式错误 | 确认是合法手机号格式 |
| `-5` / `-6` | 找不到归属地 | 号段可能过新或异常，可重试/标记 |
| `0` | 成功 | — |
> 详细排查路径见 [《手机归属地查询错误码排查》](https://www.showapi.com/guides/phone-attribution-error-codes-6)。
## 文档内部不一致与统一口径
官方文档存在少量不一致，全系列统一按下述口径处理（不照抄错误）：
1. **`areaCode` 区号**：参数表写 `0810`、返回示例写 `0871`；昆明真实区号为 `0871` → **以 `0871` 为准**。
2. **`postCode` 邮编**：参数表未登记，但返回示例与产品说明（"省、市、邮编、区号"）均有 → **列为真实字段，标注来源"返回示例/产品说明"**。
3. **`city` / `name` 占位**：参数表示例为占位符 `test` → **以真实值（昆明 / 电信）为准**。
4. **`type` 取值**：参数表示例为 `1`、返回示例为 `2`（电信） → **以枚举定义为准**（1移动/2电信/3联通/4广电/-1未知）。
## 最小代码入口（先跑通这一条）
下面这段 Python 是入门最短路径，替换 `YOUR_APPKEY` 即可运行：
```python
import requests
API_URL = "https://route.showapi.com/6-1"
APP_KEY = "YOUR_APPKEY" # 替换为你的真实 AppKey
PHONE = "18908711111"
resp = requests.get(
API_URL,
params={"appKey": APP_KEY, "num": PHONE},
timeout=10,
)
body = resp.json().get("showapi_res_body", {})
if body.get("ret_code") == 0:
print(body.get("prov"), body.get("city"), body.get("name"))
else:
print("失败，错误码：", body.get("ret_code"), "（失败不扣点数）")
```
> 多语言版本与解析细节见 [《5 分钟接入》](https://www.showapi.com/guides/phone-attribution-quickstart-6)。
## 相关资源表
| 资源 | 地址 | 说明 |
|------|------|------|
| 接口详情页 | `https://www.showapi.com/apiGateway/view/6` | 手机归属地查询产品总览与档位说明 |
| 接入点 6-1 | `https://www.showapi.com/apiGateway/view/6/1` | 单接入点参数、返回、示例详情 |
| OpenAPI 3.0（YAML） | `https://www.showapi.com/openapi/market/6.yaml` | 覆盖全部接入点的接口描述，可导入 Apifox / Postman |
| OpenAPI 3.0（JSON） | `https://www.showapi.com/openapi/market/6.json` | 同上，JSON 格式 |
| MCP 服务 | `http://www.showapi.com.cn/mcp/6/{your_appKey}` | 覆盖全部接入点的 MCP 服务地址（替换 AppKey 即用） |
| AppKey 管理 | `https://www.showapi.com/console#/myApp` | 获取 / 管理你的 AppKey |
| 档位说明 | `https://www.showapi.com/apiGateway/view/6` | 免费服务的使用档次限制详情（具体档位数字以官方页面为准） |
> 接口地址：`https://route.showapi.com/6-1?appKey={your_appKey}`；请求方式 POST / GET；必填参数仅 `num`。
## 阅读建议
按下面顺序读，能最快从"会用"走到"用好"：
1. **入门（先跑通）**：从 [《5 分钟接入》](https://www.showapi.com/guides/phone-attribution-quickstart-6) 开始，照代码拿到第一条真实返回；再读 [《返回字段全解》](https://www.showapi.com/guides/phone-attribution-response-fields-6) 搞清每个字段，读 [《错误码排查》](https://www.showapi.com/guides/phone-attribution-error-codes-6) 学会失败处理。
2. **技术（接进系统）**：按你的系统形态选——表单场景看 [《表单防错》](https://www.showapi.com/guides/phone-attribution-form-validation-6)，表格批量看 [《Excel 批量》](https://www.showapi.com/guides/phone-attribution-excel-batch-6)，要做运营商分支看 [《type 字段全解》](https://www.showapi.com/guides/phone-attribution-type-field-6)，免费档位吃紧看 [《缓存》](https://www.showapi.com/guides/phone-attribution-cache-6)。
3. **生态（现代工具链）**：治理团队看 [《OpenAPI 导入》](https://www.showapi.com/guides/phone-attribution-openapi-6)，想用 AI 对话查号看 [《MCP》](https://www.showapi.com/guides/phone-attribution-mcp-6)。
4. **行业（按角色找用法）**：客服/CRM 看 [《CRM/客服》](https://www.showapi.com/guides/phone-attribution-crm-6)，电商风控看 [《电商风控》](https://www.showapi.com/guides/phone-attribution-ecommerce-6)，物流/外卖看 [《物流外卖》](https://www.showapi.com/guides/phone-attribution-logistics-6)。
## FAQ（总目录常见问题）
**Q1：这 12 篇是同一个接口吗？**
是。全系列都围绕同一个手机归属地查询接口（apiCode=6，接入点 `6-1`）；不同文章只是从不同角色、不同工具、不同场景切入。
**Q2：接口真的免费吗？有什么限制？**
免费服务，注册后默认可免费调用，设使用档次限制（具体档位数字以官方页面为准）；失败时（`ret_code!=0`）不扣点数。高并发/批量请先做客户端校验并考虑本地缓存。
**Q3：必填参数只有 `num` 一个吗？**
是。仅 `num`（手机号字符串）为必填，无其他条件必填参数。
**Q4：返回里 `postCode` 参数表没写，能用吗？**
能用。`postCode` 在返回示例与产品说明中有，官方参数表未登记；本文系列将其列为真实字段并标注来源"返回示例/产品说明"。
**Q5：MCP 和 OpenAPI 有什么区别？该用哪个？**
OpenAPI 是给"工具/代码/治理"用的接口描述标准（导入 Apifox/Postman、生成 SDK）；MCP 是给"AI 客户端"用的工具暴露协议（在对话里直接查）。两者覆盖同一接口的同一组接入点，按你的使用方选择。
**Q6：返回的区号到底 0810 还是 0871？**
以官方实际返回为准。文档参数表曾写 `0810`、返回示例写 `0871`，昆明真实区号为 `0871`，全系列均以 `0871` 为准。
**Q7：有没有批量接口？**
没有官方批量能力。接入点 `6-1` 为单条同步请求-响应；所谓"批量"是你在客户端/脚本里逐条发，或用 MCP 时让 AI 逐条查。
**Q8：支持携号转网查询吗？**
不支持。号码携号转网后，返回结果仍按原号段归属，不会变。这是官方明确的能力边界。
**Q9：返回有经纬度吗？能在地图上标点吗？**
不返回经纬度。要用 `prov`/`city` 做地图可视化，需配合外部地理编码服务转换坐标；本接口只负责"归属地文字"。
**Q10：档位限制的具体数字是多少？**
具体使用档次数字以官方接口详情页为准，本文不编造量化数字。
**Q11：更新频率是多久？**
半年更新一次新出现的号段归属地信息，由官方维护，你无需自己维护号段库。
