最小可运行示例：用手机号归属地查询 API 快速获取省份与运营商-育师

适用场景

在用户准备、短信发送、风险控制或号码标记等环节，经常需要根据手机号判断其归属省份与运营商。手机号归属地查询 API 提供了一种标准化的方式，输入 11 位手机号即可返回 province、carrier 等字段，无需维护本地号段数据。本文围绕该 API 的最小可运行示例展开，直接从请求构造入手，配合 curl 和代码演示，让读者在 5 分钟内跑通一次调用。

接口能力边界

输入校验：严格匹配正则^1[3-9]\d{9}$，非 11 位或开头非 1[3-9] 的号码会被拒绝并返回 4000 错误码。
双形态响应：查询成功时is_found为true，且province、carrier填充具体值；若号段尚未收录（例如新放出的号段），则is_found为false，其余字段为空字符串——此时仍属于成功请求（HTTP 200，code 0），前端可以依据is_found做 UI 降级，无需额外错误分支。
缓存策略：成功结果缓存 7 天（因为号段分配相对静态），未查询到的结果缓存 1 小时（避免对新号段产生过长误判）。该策略由服务端自动执行，调用方无需关心。
隐私保护：服务端错误日志中手机号会自动脱敏（如 138****0000），调用方在本地打印日志时也应遵循类似脱敏策略。

该接口覆盖中国移动、联通、电信主流号段及虚拟运营商号段（170/171/174 等），但不支持港澳台及境外号码。

请求参数与鉴权

Query 参数

参数名	必填	类型	说明	示例
`mobile`	是	string	11 位中国大陆手机号，必须以 1[3-9] 开头	`13800138000`

Header 鉴权

接口支持两种鉴权方式（二选一）：

Authorization 头（推荐）：格式Bearer sk_live_xxx，其中sk_live_xxx是你在 API 平台获取的密钥。
X-API-Key 头（兼容）：格式sk_live_xxx，不含 Bearer 前缀。

匿名调用（不传任何鉴权头）每日有 50 次调用次数限制，适合测试阶段快速体验；生产环境建议使用密钥鉴权以避免次数受限。

最小可运行 curl 示例

以下命令直接在终端执行即可调用接口（请将$YOUR_API_KEY替换为实际密钥）：

curl -sS \ -X GET \ -H "Authorization: Bearer $YOUR_API_KEY" \ "https://v1.apizero.cn/api/mobile?mobile=13800138000"

若使用兼容头：

curl -sS \ -X GET \ -H "X-API-Key: $YOUR_API_KEY" \ "https://v1.apizero.cn/api/mobile?mobile=13800138000"

免鉴权测试（不传任何 Key 头，每日 50 次）：

curl -sS \ -X GET \ "https://v1.apizero.cn/api/mobile?mobile=13800138000"

执行后会看到类似 JSON 输出：

{ "code": 0, "data": { "carrier": "中国移动", "is_found": true, "mobile": "13800138000", "province": "北京" }, "msg": "成功", "request_id": "abc123def456" }

Python 代码接入示例

下面是一个完整的 Python 3 脚本，包含函数封装、异常处理和日志脱敏建议：

import requests import re def query_mobile_phone(mobile: str, api_key: str = "") -> dict: """ 查询手机号归属地 :param mobile: 11 位手机号 :param api_key: API 密钥，为空时使用匿名调用（每日 50 次） :return: 原始响应 JSON（dict） """ # 前置校验：避免无效请求浪费配额 if not re.match(r'^1[3-9]\d{9}$', mobile): raise ValueError(f"无效手机号格式: {mobile}") url = "https://v1.apizero.cn/api/mobile" params = {"mobile": mobile} headers = {} if api_key: headers["Authorization"] = f"Bearer {api_key}" # 注意：日志中手机号脱敏处理，只记录前三位和后四位 safe_mobile = mobile[:3] + "****" + mobile[-4:] print(f"[INFO] 正在查询手机号: {safe_mobile}") resp = requests.get(url, params=params, headers=headers, timeout=10) resp.raise_for_status() # 非 2xx 状态码会抛出异常 return resp.json() if __name__ == "__main__": # 测试：使用真实号码（可换成你自己的号） result = query_mobile_phone("13800138000", api_key="") print(result)

运行该脚本（需要requests库，可用pip install requests安装），输出类似：

{ "code": 0, "data": { "carrier": "中国移动", "is_found": true, "mobile": "13800138000", "province": "北京" }, "msg": "成功", "request_id": "req_xxxxxxxxxxxx" }

返回值解读

响应体始终为 JSON，顶层字段固定：

字段	类型	说明
`code`	number	业务状态码，0 表示成功，非 0 见错误码表格
`msg`	string	对应 code 的中文描述
`data`	object	查询结果数据
`request_id`	string	本次请求的全局唯一标识，可用于排查问题

data中字段：

字段	类型	说明
`mobile`	string	传入的手机号原值
`is_found`	boolean	是否找到归属信息
`province`	string	省份（如“广东”）；`is_found`为 false 时为空字符串
`carrier`	string	运营商（如“中国移动”“中国联通”“中国电信”或“虚拟运营商”）；未查到时为空

常见错误码解析

code	msg	触发条件	排查方向
0	成功	请求完全正常	–
4000	参数错误（手机号格式无效）	mobile 不符合 11 位数字或开头非 1[3-9]	检查前端输入校验，截取前后空格
4001	缺少必要参数	未传 mobile 参数	确认 URL query 中是否包含 mobile
4010	鉴权失败	Authorization 头格式不对或密钥无效	检查 Bearer 前缀、密钥是否有权限
4030	频率限制	请求 QPS 超过 10 次/s	在客户端实现限流，或改用异步队列
5000	服务器内部错误	服务端异常	联系服务商并提供 request_id

注意：当is_found=false时返回的仍是 code=0，不属于错误，前端应直接通过if (!data.is_found) { ... }处理。

工程化注意事项

参数校验前置：在发送 HTTP 请求前先对手机号做正则校验，避免无效请求浪费配额并降低延迟。
日志脱敏：无论在服务端还是客户端，记录日志时应将手机号中间四位替换为****，避免泄露用户隐私。接口本身已对错误日志做脱敏，但调用方自身也需注意。
缓存策略配合：接口服务端已内置 7 天缓存（成功结果），因此客户端无需再对相同号码做额外缓存；但对于未查询到的结果（is_found=false），客户端可考虑本地短暂缓存（如 10 分钟）以减少重复查询。
并发限流：接口 QPS 为 10/s，如果同时有大量查询需求，应在客户端进行令牌桶限速或排队。使用异步 HTTP 客户端（如 aiohttp）可以批量发送请求但需注意控制速率。
错误重试：对于 5xx 错误（如 5000），可间隔 1~2 秒重试至多 2 次；对于 4xx 错误（如 4000、4010）不应重试，应修复请求参数。
测试号码：开发阶段可使用13800138000等公开测试号，但生产环境中需确保手机号来源合法合规。