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