手机号归属地接口用于根据 11 位中国大陆手机号查询归属省份、城市与运营商。对于用户注册信息补全、订单风控辅助、客服系统展示等场景这是后端经常需要的一次性查询能力。本文从零开始说明第一次调用需要准备什么、最小请求怎么发、返回值怎么看。适用场景与能力边界典型用途包括用户填写手机号后自动带出归属地与运营商减少手工输入在下单或提现流程中把归属地作为风控辅助字段客服工单里展示来电号码的归属信息。接口支持移动、联通、电信主流号段也覆盖 170、171、174 等虚拟运营商号段。需要明确边界接口返回的是号段归属不是实时位置也不代表号码当前使用者的实际所在地它不验证号码是否真实在用不发送短信也不提供实名校验能力。接口有一个值得注意的设计采用双形态响应。查询成功时is_foundtrue并返回归属字段号段未收录时is_foundfalse且归属字段为空。后者不是错误前端可以直接用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?mobile13800138000keyYOUR_API_KEY使用请求头鉴权的写法curl -H Authorization: Bearer YOUR_API_KEY \ https://v1.apizero.cn/api/mobile?mobile13800138000接口方法为 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] fBearer {key} resp requests.get(url, paramsparams, headersheaders, timeout15) 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 抛RuntimeErroris_foundfalse则是正常的查询结果走业务分支即可。返回字段解读成功响应的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 中的 KeyHTTP 429 或限流提示超出调用频率限制控制并发QPS 以文档为准is_found为 false号段未收录如新放号段属于正常结果不是接口故障特别注意最后一行is_foundfalse与接口报错是两回事前者是有效响应不应触发告警或重试。工程化注意事项本地先做正则校验。接口侧规则是^1[3-9]\d{9}$本地用同一规则过滤可以避免 4000 错误也减少无效请求。利用缓存特性。接口自身对成功结果缓存 7 天号段分配相对静态未查询到的结果缓存 1 小时避免长期误判新放号段。业务侧如需在本地再做一层缓存建议采用相同量级命中成功的缓存久一些未命中的短一些否则新号段上线后会被自己的缓存长期挡住。Key 放服务端。归属地查询常出现在注册与下单流程中由后端代理调用前端不接触密钥。日志脱敏。接口在错误日志中会自动将手机号脱敏为138****0000形式。业务侧自己的日志同样应遵循这一做法手机号属于个人信息不要明文落盘。区分展示与决策。归属地适合作为展示信息或风控的辅助信号不建议单独作为拦截依据尤其对虚拟运营商号段应结合其他规则综合判断。参考文档接口文档接口地址