手机号归属地查询 API｜基于号段解析，查询号码省份、城市与运营商信息
一、技术简介
手机号归属地查询 API 是一种面向开发者与业务系统的结构化数据接口服务。它的核心能力是：输入一个手机号（或号码前段），基于号段解析规则，返回该号码对应的省份、城市、邮政编码、电话区号、运营商等信息。
在国内三网（移动、电信、联通）体系中，手机号段与归属地、运营商之间存在一定的映射关系。随着携号转网、号段重新分配等因素，"号段—归属地"并非固定不变，任何单一映射表都会随时间产生偏差。本接口通过持续更新的号段库，输出当前可用的归属地信息，供业务侧在风控、营销、坐席、区域运营等场景做前置判断。
定位说明：本接口返回的是"号码在分配层面的归属地"，而非号码当前实际使用位置。它适合做粗粒度的地域与运营商画像，不适合用于实时定位。
二、能力概览
| 能力项 | 说明 |
|---|---|
| 查询输入 | 单个手机号（Query 参数 num） |
| 解析维度 | 省份、城市、邮编、电话区号、运营商、号段 |
| 覆盖网络 | 国内移动、电信、联通三网号段 |
| 返回格式 | JSON，统一包一层网关响应结构 |
| 鉴权方式 | APPCODE 简单身份认证 |
| 请求方法 | GET |
接口返回的每个号码都会附带 ret_code 状态码，0 表示解析成功。号段（num 字段）、运营商类型（type 字段：1 移动 / 2 电信 / 3 联通）等，可与省市、邮编、区号组合，满足不同粒度场景的取用。
三、适用场景
- 风控与反欺诈：在注册、登录、支付环节，结合号码归属地做异地登录、异地开卡等异常的初筛。
- 营销与区域运营：按省市维度做分维度推送、本地化内容、区域活动圈选。
- 坐席与外呼路由：依据号码归属地就近分配坐席，或在外呼前做归属地标注。
- 数据补全：在用户未主动填写省市时，用号码归属地做字段补全，降低用户填写成本。
- 数据分析：在用户画像、留存分析中，把归属地作为地域标签参与分组。
四、接入流程
- 获取凭据：在控制台创建 / 查看凭据，取得 APPCODE。
- 构造请求：以 GET 方式调用接口，在 Query 中传入
num（要查询的手机号）。 - 携带鉴权：在请求头中加入
Authorization: APPCODE <你的appcode>。 - 解析响应：读取返回 JSON 中的网关状态码与
showapi_res_body业务字段。 - 兜底处理：对解析失败、号段未命中的情况做降级与日志记录。
五、调用示例与返回结构
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
num |
string | 是 | 要查询的手机号，如 18908712345 |
鉴权
采用 APPCODE 简单身份认证，请求头形如：
Authorization: APPCODE <你的appcode>
调用地址、完整端点等信息请以控制台展示为准。
返回结构
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": {
"ret_code": 0,
"prov": "云南",
"city": "昆明",
"areaCode": "0871",
"postCode": "650000",
"name": "电信",
"type": 2,
"provCode": "530000",
"cityCode": "530100",
"num": 1890871
}
}
字段说明：
| 字段 | 说明 |
|---|---|
ret_code |
业务状态码，0 为成功，其他为失败 |
prov |
省份 |
city |
城市 |
areaCode |
电话区号 |
postCode |
邮政编码 |
name |
运营商名称 |
type |
运营商类型，1 移动 / 2 电信 / 3 联通 |
provCode |
该省身份证开头几位 |
cityCode |
该城市身份证开头几位 |
num |
号段 |
六、在线调试实录
在控制台调试台输入 num=18908712345，携带 APPCODE 发起 GET 请求，返回中 showapi_res_body 给出省份"云南"、城市"昆明"、运营商"电信"、区号"0871"等字段，与号段解析结果一致。
调试建议：
- 先用一个已知归属地的号码做冒烟测试，确认
ret_code=0。 - 再测一个未命中的号段，观察失败返回结构。
- 记录响应耗时，评估线上接口的超时阈值。
七、调用限制与规范
- 频率控制：接口有并发 / 频率限制，生产侧请设置 QPS 阈值与限流，避免突发打满。
- 幂等与去重：相同号码可加本地 / 缓存层（如 Redis）做结果缓存，降低重复调用。
- 最小必要：只采集业务必需的号码，避免大批量扫号段。
- 日志脱敏：号码属个人信息，落库与打日志时需脱敏（如中间四位打码）。
- 合规使用：仅用于合法业务目的，不用于骚扰、精准定位个人等违规用途。
八、能力边界与免责
- 支持：国内三网号段的基础归属地、运营商、省市、邮编、区号解析。
- 不支持 / 边界：
- 不返回实时位置（GPS、基站），号段归属地 ≠ 当前所在地。
- 携号转网后号码的归属地信息可能无法及时反映，结果仅供参考。
- 部分新放号段或特殊号段可能未命中，返回
ret_code非 0。
- 免责：解析结果用于业务辅助判断，最终决策请结合多源数据交叉验证。
九、错误码排查
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
showapi_res_code 非 0 |
鉴权失败 / 请求格式错误 | 核对 APPCODE 与请求头，确认 GET 方法与 Query 参数 |
ret_code 非 0 |
号段未命中 / 号码不合规 | 校验号码长度格式，对未命中做降级 |
| 请求超时 | 网络抖动 / 并发过高 | 加超时与重试，控制并发 |
| 频控报错 | 超过频率上限 | 引入缓存与限流，削峰 |
十、技术 FAQ
Q：号段归属地和实际所在地是一回事吗？
A：不是。号段归属地反映号码分配时的地区，携号转网或跨地使用时可能与实际位置不一致。
Q：查询失败时如何降级？
A：返回 ret_code 非 0 时，可回退到用户主动填写或 IP 地理库等其他信号，避免单点依赖。
Q：能否批量查询？
A：本接口为单号码查询，批量场景建议在调用侧做并发控制与缓存，避免触发频控。
Q：数据更新频率如何？
A：号段库会随运营商放号动态更新，具体时效以控制台说明为准。
十一、内容小结
手机号归属地查询 API 通过号段解析，提供号码的省份、城市、邮编、区号与运营商信息，适用于风控、营销、坐席路由、数据补全等前置判断场景。接入时注意三点：一是它返回的是"分配层归属地"而非实时位置，结果需结合多源交叉验证；二是携带 APPCODE 鉴权并控制调用频率，加缓存与限流；三是号码属个人信息，落库打日志需脱敏、合规使用。
