最小可运行示例：用手机号归属地查询 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 200code 0前端可以依据is_found做 UI 降级无需额外错误分支。缓存策略成功结果缓存 7 天因为号段分配相对静态未查询到的结果缓存 1 小时避免对新号段产生过长误判。该策略由服务端自动执行调用方无需关心。隐私保护服务端错误日志中手机号会自动脱敏如 138****0000调用方在本地打印日志时也应遵循类似脱敏策略。该接口覆盖中国移动、联通、电信主流号段及虚拟运营商号段170/171/174 等但不支持港澳台及境外号码。请求参数与鉴权Query 参数参数名必填类型说明示例mobile是string11 位中国大陆手机号必须以 1[3-9] 开头13800138000Header 鉴权接口支持两种鉴权方式二选一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?mobile13800138000若使用兼容头curl -sS \ -X GET \ -H X-API-Key: $YOUR_API_KEY \ https://v1.apizero.cn/api/mobile?mobile13800138000免鉴权测试不传任何 Key 头每日 50 次curl -sS \ -X GET \ https://v1.apizero.cn/api/mobile?mobile13800138000执行后会看到类似 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: 原始响应 JSONdict # 前置校验避免无效请求浪费配额 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] fBearer {api_key} # 注意日志中手机号脱敏处理只记录前三位和后四位 safe_mobile mobile[:3] **** mobile[-4:] print(f[INFO] 正在查询手机号: {safe_mobile}) resp requests.get(url, paramsparams, headersheaders, timeout10) 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顶层字段固定字段类型说明codenumber业务状态码0 表示成功非 0 见错误码表格msgstring对应 code 的中文描述dataobject查询结果数据request_idstring本次请求的全局唯一标识可用于排查问题data中字段字段类型说明mobilestring传入的手机号原值is_foundboolean是否找到归属信息provincestring省份如“广东”is_found为 false 时为空字符串carrierstring运营商如“中国移动”“中国联通”“中国电信”或“虚拟运营商”未查到时为空常见错误码解析codemsg触发条件排查方向0成功请求完全正常–4000参数错误手机号格式无效mobile 不符合 11 位数字或开头非 1[3-9]检查前端输入校验截取前后空格4001缺少必要参数未传 mobile 参数确认 URL query 中是否包含 mobile4010鉴权失败Authorization 头格式不对或密钥无效检查 Bearer 前缀、密钥是否有权限4030频率限制请求 QPS 超过 10 次/s在客户端实现限流或改用异步队列5000服务器内部错误服务端异常联系服务商并提供 request_id注意当is_foundfalse时返回的仍是 code0不属于错误前端应直接通过if (!data.is_found) { ... }处理。工程化注意事项参数校验前置在发送 HTTP 请求前先对手机号做正则校验避免无效请求浪费配额并降低延迟。日志脱敏无论在服务端还是客户端记录日志时应将手机号中间四位替换为****避免泄露用户隐私。接口本身已对错误日志做脱敏但调用方自身也需注意。缓存策略配合接口服务端已内置 7 天缓存成功结果因此客户端无需再对相同号码做额外缓存但对于未查询到的结果is_foundfalse客户端可考虑本地短暂缓存如 10 分钟以减少重复查询。并发限流接口 QPS 为 10/s如果同时有大量查询需求应在客户端进行令牌桶限速或排队。使用异步 HTTP 客户端如 aiohttp可以批量发送请求但需注意控制速率。错误重试对于 5xx 错误如 5000可间隔 1~2 秒重试至多 2 次对于 4xx 错误如 4000、4010不应重试应修复请求参数。测试号码开发阶段可使用13800138000等公开测试号但生产环境中需确保手机号来源合法合规。参考文档官方文档页https://apizero.cn/aidocs/mobile原始 Markdown 文档https://apizero.cn/aidocs/mobile/raw.md