手机号归属地查询API实战：业务场景与工程接入详解
适用场景
在互联网业务中，手机号归属地信息常被用于以下场景：
- 用户准备风控：检测准备手机号的归属地与IP定位是否一致，识别异地登录或欺诈行为。
- 营销地域化：根据用户手机归属地推送本地活动或方言客服，提升转化率。
- 数据清洗与补全：对存量用户档案中的手机号补充省份、运营商信息，用于统计报表。
- 客服工单自动分配：将用户来电归属地对应的区域客服组，减少转接时长。
这类需求通常要求接口响应快、数据准确，且能区分未收录号段。本文讲解的归属地查询API支持主流运营商及虚拟运营商号段，并提供明确的 is_found 标识，便于前端直接做分支处理。
接口能力边界
在集成前，需要明确该接口的能力约束：
- 查询范围：仅支持中国大陆11位手机号（必须
1[3-9]开头），其他号码直接返回 4000 错误。 - 数据时效：号码段分配相对静态，成功结果缓存 7 天；未查询到的结果缓存 1 小时，避免新发放号段长期误判。
- 并发限制：QPS 10/s，短时超出会返回限流错误。
- 鉴权等级：支持匿名调用（每日50次限额）和 API Key 鉴权（更高额度，以实际文档为准）。
- 响应形态：双形态响应——号段已收录时
is_found=true并返回province、carrier；未收录时is_found=false，其余字段为空（非错误，业务逻辑可直接判断）。
请求说明
Query参数
| 参数名 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
| mobile | 是 | string | 11位中国大陆手机号，必须匹配正则^1[3-9]\d{9}$ | 13800138000 |
鉴权方式
API 支持两种调用方式：
- 匿名调用（每日50次内）：不携带 Authorization 头，适用于开发调试或低频场景。
- API Key 鉴权：在 Header 中添加
Authorization: Bearer sk_live_xxxxxxxxxxxxxx（以实际申请的 Key 为准），可获取更高调用额度。
推荐在生产环境中使用 API Key 鉴权，以避免匿名额度限制。
快速接入：curl 与代码示例
curl 示例
以下是通过环境变量APIZERO_API_KEY传递 API Key 的 curl 命令（匿名调用则去掉-H头）：
# 使用 API Key 鉴权（推荐） curl -sS \ -X GET \ -H "Authorization: Bearer ${APIZERO_API_KEY}" \ "https://v1.apizero.cn/api/mobile?mobile=13800138000" # 匿名调用（每日50次） curl -sS -X GET "https://v1.apizero.cn/api/mobile?mobile=13800138000"响应示例（格式化后）：
{ "code": 0, "data": { "carrier": "中国移动", "is_found": true, "mobile": "13800138000", "province": "北京" }, "msg": "成功", "request_id": "abc123def456" }Python 代码示例（requests）
import requests import os # 从环境变量读取 API Key（匿名调用可设为 None） API_KEY = os.environ.get("APIZERO_API_KEY") url = "https://v1.apizero.cn/api/mobile" mobile = "13800138000" headers = {} if API_KEY: headers["Authorization"] = f"Bearer {API_KEY}" params = {"mobile": mobile} response = requests.get(url, params=params, headers=headers) if response.status_code != 200: print(f"HTTP 错误: {response.status_code}") else: result = response.json() if result["code"] == 0: data = result["data"] if data["is_found"]: print(f"号码 {mobile} 归属地: {data['province']} {data['carrier']}") else: print(f"号码 {mobile} 号段暂未收录") else: print(f"API 错误: {result['msg']} (code={result['code']})")返回值解读
成功响应（200 + code=0 + is_found=true）
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| data.carrier | string | 运营商，如 “中国移动”、“中国联通”、“中国电信” |
| data.is_found | bool | 是否查询到归属地信息 |
| data.mobile | string | 请求的原始手机号 |
| data.province | string | 归属省份/直辖市，如 “北京”、“广东” |
| msg | string | 提示信息 |
| request_id | string | 请求唯一标识，可用于日志追踪 |
号段未收录响应（200 + code=0 + is_found=false）
此时data.province和data.carrier为空字符串，data.is_found为 false。前端可直接通过if (res.data.is_found)做展示/隐藏处理，无需将空字段视为错误。
错误响应
| HTTP状态码 | code | msg | 说明 |
|---|---|---|---|
| 200 | 4000 | 参数错误 | mobile 不符合11位手机号格式，或非1[3-9]开头 |
| 401 | — | — | API Key 无效或未授权（匿名调用超出限额时可能返回 401） |
| 429 | — | — | 请求频率超过 QPS 配额（10/s） |
注意：错误日志中手机号会自动脱敏显示（如138****0000），保护用户隐私。
常见错误与排查
- 收到 4000 错误：检查 mobile 参数是否严格满足
1[3-9]开头且长度为 11。末尾多空格或中间含横线也会被拒。 - 匿名调用返回 401：很可能今日调用次数限制（50次）已用尽。升级到 API Key 鉴权即可。
- 响应缓慢或超时：确认本地网络能否访问
v1.apizero.cn，检查是否存在代理干扰。可设置 5 秒超时并用重试机制。 - is_found=false 但确实存在该号段：可能该号段为新开放批号，API 数据尚未更新（缓存 1 小时），稍后重试即可。生产环境建议定时缓存成功结果以减少重复请求。
工程化注意事项
- 缓存策略：成功结果可缓存至少 1 天（号段分配稳定），但不要缓存未找到的结果超过 5 分钟，避免错失新数据。
- QPS 控制：若并发超过 10/s，需在客户端实现令牌桶或滑动窗口限流，或使用请求队列。
- 异常回退：当 API 连续返回错误或超时时，应提供本地兜底数据（例如只显示运营商，省份显示“未知”），保证业务流程不中断。
- 日志脱敏：无论在请求日志还是错误日志中，都应对手机号中间四位进行掩码处理（如
138****0000），API 自身已做了脱敏，但本地日志也需遵循此规范。 - 参数校验前置：在客户端先正则校验
^1[3-9]\d{9}$，避免无效请求浪费 API 配额。
参考文档
- 手机号归属地 API 文档
- 原始文档 Markdown 版