手机归属地查询 · 官方指南总目录
约 20 分钟 入门手机号码归属地查询官方指南目录免费接口API 文档索引
# 手机归属地查询 · 官方指南总目录
接口：手机号码归属地查询（apiCode=6，接入点 6-1）｜是否免费：是，注册后默认可调用，设使用档次限制｜请求方式：POST / GET｜返回格式：JSON｜最后实测核对：2026-09-18
这是手机号码归属地查询（易源 ShowAPI，apiCode=6）的官方指南总目录。接口只需传入一个手机号 `num`，即可返回省、市、运营商、号段、区号、邮编、省/市编码等信息。免费服务，注册后默认可调用，失败时 `ret_code != 0` 且不扣点数。
全系列共 12 篇，按入门、技术集成、工具链、业务场景四层组织。下面先给接口速览，再分层列出全部文章，随后是字段速查、错误码速查、文档与实测的差异口径、最小代码入口、相关资源表，最后是阅读建议与 FAQ。
## 接口一句话速览
| 项目 | 内容 |
|------|------|
| 产品名 | 手机号码归属地查询 |
| apiCode | 6 |
| 分类 | 企业服务 |
| 服务商 | 昆明秀派科技有限公司（易源官方自营） |
| 接入点 | 6-1，全接口仅此一个，同步请求-响应，无订阅推送、无回调、无官方批量能力 |
| 接口地址 | `https://route.showapi.com/6-1` |
| 请求方式 | POST 或 GET |
| 鉴权 | Query 参数 `appKey` |
| 必填参数 | `num`（String，要查询的手机号码） |
| 返回格式 | JSON，业务数据在 `showapi_res_body` 内 |
| 返回字段 | `prov` `city` `name` `num` `provCode` `cityCode` `areaCode` `postCode` `type` `ret_code` `remark`，共 11 个 |
| 运营商枚举 `type` | 1 移动、2 电信、3 联通、4 广电、-1 未知 |
| 状态码 `ret_code` | 0 成功；-1 号段存在但归属地字段为空；-2 不是 11 位；-3 含非数字字符；-4 格式错误；-5 / -6 找不到归属地 |
| 超时 | `x-read-timeout: 10`、`x-connect-timeout: 10` |
| 数据更新 | 每半年同步一次新增号段归属信息 |
| 计费 | 免费服务，设使用档次限制；失败不扣点数 |
| 集成能力 | MCP 服务、OpenAPI 3.0（YAML / JSON） |
| 匹配粒度 | 前 7 位号段，实测后 4 位不影响结果 |
| 适用范围 | 不支持携号转网查询；返回粒度到市一级，不含经纬度 |
## 全系列文章（12 篇）
### 一、入门篇（先跑通，再深入）
1. [手机归属地查询接口怎么用？从 AppKey 到第一条真实返回的完整路径](https://www.showapi.com/guides/phone-attribution-quickstart-6)
注册拿 AppKey、发请求、解析 `showapi_res_body` 的最短路径，含 Python / cURL / Node.js 可运行代码。刚拿到 AppKey、想立刻看到第一条真实返回时先看这篇。
2. [手机归属地查询返回字段全解：11 个字段的类型、取值与粒度](https://www.showapi.com/guides/phone-attribution-response-fields-6)
逐个拆解 11 个业务字段的类型、真实取值与来源，含文档未登记字段的处理方式。要把字段映射进数据库或结构体时看这篇。
3. [手机归属地查询返回 -2、-3、-4 是什么意思？错误码逐条对照与排查](https://www.showapi.com/guides/phone-attribution-error-codes-6)
每个 `ret_code` 的实测触发条件与排查路径，配客户端前置校验代码。查询失败要快速定位原因时看这篇。
### 二、技术集成篇（把接口接进你的系统）
4. [手机归属地查询 type 字段全解：1移动 2电信 3联通 4广电 -1未知怎么用](https://www.showapi.com/guides/phone-attribution-type-field-6)
运营商枚举的完整用法：取值来源、与 `name` 的分工、未知值兜底。业务要按运营商走分支时看这篇。
5. [手机归属地查询：在注册表单里做实时校验与运营商识别](https://www.showapi.com/guides/phone-attribution-form-validation-6)
表单场景的两层校验、防抖、地域一致性比对与提示文案分档。做注册、开户、留资表单时看这篇。
6. [手机归属地查询：用 Python 给 Excel 号码表批量补归属地](https://www.showapi.com/guides/phone-attribution-excel-batch-6)
号码去重、断点续跑、失败重试与结果写回，含档位与并发节奏对照。手上有一张号码表要补地域标签时看这篇。
7. [手机归属地查询按前 7 位号段做缓存：实测粒度与 Redis 实现](https://www.showapi.com/guides/phone-attribution-cache-6)
缓存粒度的对照实验、内存 LRU 与 Redis 两套实现、成功与失败结果的 TTL 分档。调用量接近档位上限时看这篇。
### 三、工具链篇（用现代工具链管理接口）
8. [手机归属地查询 MCP 服务：在 AI 客户端里直接问号码归属地](https://www.showapi.com/guides/phone-attribution-mcp-6)
MCP 服务地址、客户端配置、实测握手流程与 SSE 返回解析。想用对话方式查号码时看这篇。
9. [手机归属地查询 OpenAPI 文档：用 Postman 与 Swagger UI 管理接口](https://www.showapi.com/guides/phone-attribution-openapi-6)
OpenAPI 文档内容、导入 Postman、Swagger UI 部署、Mock 与 SDK 生成，含文档与实测的差异清单。做 API 治理与测试时看这篇。
### 四、业务场景篇（按角色找用法）
10. [手机归属地查询接进 CRM：来电弹屏显示归属地与运营商](https://www.showapi.com/guides/phone-attribution-crm-6)
弹屏链路的超时与降级设计、话术分流、结果推送与地域分组。做客服系统、呼叫中心时看这篇。
11. [手机归属地查询在电商风控里能做什么：可用维度与不成立的用法](https://www.showapi.com/guides/phone-attribution-ecommerce-6)
地域一致性、号段分布、运营商三类可用维度，以及三种不成立的用法。做风控特征设计时看这篇。
12. [手机归属地查询：按 cityCode 给收货号码匹配派送区域](https://www.showapi.com/guides/phone-attribution-logistics-6)
用城市编码做区域匹配、号码与地址一致性检查、批量回调的调用节奏。做物流调度与外卖派单时看这篇。
## 返回字段速查
以 2026-09-18 实测返回为例，`showapi_res_body` 内的字段如下。
| 字段 | 实测类型 | 含义 | 实测示例值 |
|------|----------|------|------------|
| `prov` | String | 省 | 北京 |
| `city` | String | 市，粒度到市 | 北京 |
| `name` | String | 运营商名称，实测为套餐或品牌名 | 移动全球通卡 |
| `num` | Number | 号段，前 7 位 | 1380013 |
| `provCode` | String | 省别编码，本省身份证前几位 | 110000 |
| `cityCode` | String | 城市编码，本城市身份证前几位 | 110100 |
| `areaCode` | String | 城市区号，含前导零 | 010 |
| `postCode` | String | 邮政编码，参数表未登记 | 100000 |
| `type` | Number | 运营商枚举 | 1 |
| `ret_code` | Number | 业务状态码 | 0 |
| `remark` | String | 补充说明，参数表未登记，失败时给出原因 | 空 |
逐字段解读见[返回字段全解](https://www.showapi.com/guides/phone-attribution-response-fields-6)。
## 错误码速查
| `ret_code` | 含义 | 实测触发条件（2026-09-18） |
|------------|------|----------------------------|
| 0 | 成功 | 前 7 位在号段库中匹配 |
| -1 | 未登记 | 号段识别到但归属地字段全空，如 `19999999999` |
| -2 | 手机号输入的不是 11 位 | 长度 9 位及以下，或含 `+`、`.` |
| -3 | 手机号中有非数字字符 | 含 ASCII 字母 |
| -4 | 手机号格式错误 | 全角数字、中文数字 |
| -5 / -6 | 找不到归属地 | 11 位纯数字但号段不存在 |
失败时 `showapi_fee_num` 为 0，不消耗调用额度。逐条排查路径见[错误码逐条对照](https://www.showapi.com/guides/phone-attribution-error-codes-6)。
## 文档与实测的差异口径
官方文档与实测返回存在少量差异，全系列统一按实测口径处理，同时标注文档原文。
| 项目 | 文档口径 | 实测口径 |
|------|----------|----------|
| 返回字段个数 | OpenAPI 登记 9 个 | 真实返回 11 个，多出 `postCode`、`remark` |
| `provCode` 类型 | Number | String，返回 `"110000"` |
| `-1` 状态码 | 未登记 | 真实存在，号段识别到但归属地字段为空 |
| 号码长度校验 | `-2` 表示不是 11 位 | 10 位与 12 位照常返回成功，`-2` 的实测边界是 9 位及以下 |
| `remark` 字段 | 未登记 | 真实返回，失败时给出原因文字 |
## 最小代码入口
下面这段 Python 是入门最短路径，替换 `YOUR_APPKEY` 即可运行。
```python
import requests
API_URL = "https://route.showapi.com/6-1"
APP_KEY = "YOUR_APPKEY" # 替换成你的真实 AppKey
PHONE = "13800138000"
resp = requests.get(
API_URL,
params={"appKey": APP_KEY, "num": PHONE},
timeout=10, # 对齐官方 x-read-timeout
)
data = resp.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(data.get("showapi_res_error"))
body = data.get("showapi_res_body", {})
if body.get("ret_code") == 0:
print(body.get("prov"), body.get("city"), body.get("name"), body.get("num"))
else:
print("查询失败，ret_code =", body.get("ret_code"), "|", body.get("remark"))
```
多语言版本与解析细节见[接口接入完整路径](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 | 覆盖全部接入点的接口描述 |
| OpenAPI 3.0（JSON） | https://www.showapi.com/openapi/market/6.json | 同上，JSON 格式 |
| MCP 服务 | http://www.showapi.com.cn/mcp/6/{your_appKey} | 替换 AppKey 即用，注意域名为 `.com.cn` |
| AppKey 管理 | https://www.showapi.com/console#/myApp | 获取与管理 AppKey |
| 免费接口与档位 | https://www.showapi.com/free-api | L0 到 L4 的每日调用量、并发上限与积分 |
## 阅读建议
按下面的顺序读，能最快从「会用」走到「用好」。
入门三篇先跑完：[接口接入完整路径](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) 学会失败处理。
技术集成四篇按系统形态选：表单场景看[表单校验](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)。
工具链两篇按使用方选：AI 客户端看 [MCP](https://www.showapi.com/guides/phone-attribution-mcp-6)，治理与测试看 [OpenAPI](https://www.showapi.com/guides/phone-attribution-openapi-6)。
业务场景三篇按角色看：客服看 [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：接口免费吗？有什么限制？**
免费服务，注册后默认可调用，设使用档次限制。免费档位从 L0 起算，每日 100 次、并发 1 QPS，可用平台积分兑换 L1 到 L4 更高档位。失败时 `ret_code != 0`，不扣点数。
**Q3：必填参数只有 `num` 一个吗？**
是。只有 `num`（手机号字符串）必填，没有其他条件必填参数。
**Q4：返回里 `postCode` 和 `remark` 参数表没写，能用吗？**
能用。这两个字段在真实返回里存在，只是官方 OpenAPI 参数表未登记。解析时按可选字段处理，用 `.get()` 兜底。
**Q5：接口有批量能力吗？**
接入点 6-1 是单条同步请求-响应，没有批量入口、没有订阅推送。批量由客户端循环实现，先取前 7 位去重再循环可以显著减少请求数。
**Q6：为什么 10 位输入也能查出来？**
实测确认接口按前 7 位号段匹配，长度不是硬校验。10 位和 12 位输入照常返回成功，长度 9 位及以下才返回 `-2`。
**Q7：支持携号转网查询吗？**
不支持。号码办理携号转网后，返回的运营商仍按原号段归属。
**Q8：返回里有经纬度吗？**
没有。要用 `prov`、`city` 做地图标点，需要再走一次外部地理编码服务。
**Q9：数据多久更新一次？**
每半年同步一次新增号段归属信息，由官方维护。
**Q10：MCP 和 OpenAPI 该用哪个？**
按使用方选。OpenAPI 面向代码、测试与治理工具；MCP 面向支持 MCP 的 AI 客户端。两者覆盖同一个接入点。
- **本系列共 12 篇**：本页即[手机归属地查询指南总目录](https://www.showapi.com/guides/phone-attribution-guides-6)。
