手机号归属地接口用于根据 11 位中国大陆手机号查询归属省份、城市与运营商。对于用户注册信息补全、订单风控辅助、客服系统展示等场景，这是后端经常需要的一次性查询能力。本文从零开始，说明第一次调用需要准备什么、最小请求怎么发、返回值怎么看。
适用场景与能力边界
典型用途包括：用户填写手机号后自动带出归属地与运营商，减少手工输入；在下单或提现流程中把归属地作为风控辅助字段；客服工单里展示来电号码的归属信息。
接口支持移动、联通、电信主流号段，也覆盖 170、171、174 等虚拟运营商号段。需要明确边界：接口返回的是号段归属，不是实时位置，也不代表号码当前使用者的实际所在地；它不验证号码是否真实在用，不发送短信，也不提供实名校验能力。
接口有一个值得注意的设计：采用双形态响应。查询成功时is_found=true并返回归属字段；号段未收录时is_found=false且归属字段为空。后者不是错误，前端可以直接用if判断，不需要走异常分支。
调用前的准备
需要两样东西：一个待查询的 11 位手机号，以及一个 API Key。
接口对手机号做严格校验，正则规则为^1[3-9]\d{9}$。也就是说，必须是以 1 开头、第二位为 3 到 9、总长 11 位的纯数字。不满足该规则的号码会直接返回业务码 4000，不会进入归属查询环节。因此调用前先做本地格式过滤，可以省掉一次无效请求。
API Key 从平台的账号密钥页面获取。鉴权兼容Authorization: Bearer <API_KEY>请求头、X-API-Key请求头，或 Query 中的key参数。本文示例使用 Query 参数形式，便于 curl 直接复制。
最小请求：curl 示例
把YOUR_API_KEY替换为实际 Key、13800138000替换为待查号码：
curl "https://v1.apizero.cn/api/mobile?mobile=13800138000&key=YOUR_API_KEY"使用请求头鉴权的写法：
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://v1.apizero.cn/api/mobile?mobile=13800138000"接口方法为 GET，唯一必填参数是mobile，值为 11 位数字字符串。
Python 接入示例
下面封装一个带本地格式预校验、超时与业务码判断的调用函数：
import os import re import requests MOBILE_RE = re.compile(r"^1[3-9]\d{9}$") def query_mobile(mobile: str, api_key: str | None = None) -> dict: if not MOBILE_RE.match(mobile): raise ValueError(f"手机号格式不合法: {mobile}") url = "https://v1.apizero.cn/api/mobile" params = {"mobile": mobile} headers = {} key = api_key or os.environ.get("APIZERO_KEY") if key: headers["Authorization"] = f"Bearer {key}" resp = requests.get(url, params=params, headers=headers, timeout=15) resp.raise_for_status() payload = resp.json() if payload.get("code") != 0: raise RuntimeError(f"接口返回错误: code={payload.get('code')}, msg={payload.get('msg')}") return payload["data"] data = query_mobile("13800138000") if data.get("is_found"): print(data.get("province"), data.get("city"), data.get("carrier")) else: print("号段未收录")这里的关键是把三种情况分开：本地格式不合法抛ValueError；接口业务码非 0 抛RuntimeError；is_found=false则是正常的查询结果，走业务分支即可。
返回字段解读
成功响应的code == 0，核心数据在data内。字段含义如下（结构与名称以文档为准）：
| 字段 | 含义 |
|---|---|
mobile | 回显被查询的号码 |
is_found | 是否查询到号段归属，布尔值 |
province | 归属省份，未收录时为空 |
city | 归属城市，未收录时为空 |
carrier | 运营商名称，未收录时为空 |
读取逻辑应当是先判断is_found，再取具体字段。不要假设province永远非空，否则在未收录号段上会得到空字符串甚至null，导致展示层出现“undefined”。部分号段的城市字段可能没有细分到市级，具体表现以文档为准。
常见错误与排查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 业务码 4000 | 号码不是 11 位、非 1 开头、第二位不在 3-9 范围 | 用^1[3-9]\d{9}$本地先校验 |
code非 0，提示鉴权失败 | Key 无效、缺失或未正确传递 | 检查 Header 或 Query 中的 Key |
| HTTP 429 或限流提示 | 超出调用频率限制 | 控制并发，QPS 以文档为准 |
is_found为 false | 号段未收录，如新放号段 | 属于正常结果，不是接口故障 |
特别注意最后一行：is_found=false与接口报错是两回事，前者是有效响应，不应触发告警或重试。
工程化注意事项
本地先做正则校验。接口侧规则是^1[3-9]\d{9}$，本地用同一规则过滤可以避免 4000 错误，也减少无效请求。
利用缓存特性。接口自身对成功结果缓存 7 天（号段分配相对静态），未查询到的结果缓存 1 小时（避免长期误判新放号段）。业务侧如需在本地再做一层缓存，建议采用相同量级：命中成功的缓存久一些，未命中的短一些，否则新号段上线后会被自己的缓存长期挡住。
Key 放服务端。归属地查询常出现在注册与下单流程中，由后端代理调用，前端不接触密钥。
日志脱敏。接口在错误日志中会自动将手机号脱敏为138****0000形式。业务侧自己的日志同样应遵循这一做法，手机号属于个人信息，不要明文落盘。
区分展示与决策。归属地适合作为展示信息或风控的辅助信号，不建议单独作为拦截依据，尤其对虚拟运营商号段应结合其他规则综合判断。
参考文档
- 接口文档
- 接口地址