手机号归属地查询接口

更新时间：2026-09-18

接口说明

手机号归属地查询接口，通过 bizContent 中的 mobile 参数查询手机号归属地信息，包括省份、城市和运营商。。

接口信息

适用对象：间连商户
请求 URL：https://openapi.shuhuipay.com/v1/query/mobile
请求方法：POST

ℹ️ 公共参数说明详见通用规则 - API公共参数部分

WARNING

该接口用于查询手机号码的归属地信息，支持11位完整手机号或7位号段
传入11位手机号时自动截取前7位进行号段匹配
返回信息包含省份、城市、运营商及完整地址
该接口无需登录，无需权限验证

请求参数

bizContent 业务参数

参数名	类型	必填	参数说明
`mobile`	String	Y	手机号码，支持以下格式： • 11位完整手机号：如 `13800138000`，系统自动截取前7位查询 • 7位号段：如 `1380013`，直接查询

WARNING

⚠️ 格式要求：

手机号必须以 1 开头，第二位为 3-9
仅支持中国大陆手机号格式
号段不足7位或超过11位将返回格式错误

请求示例

完整手机号查询：

json

{
  "appId": "your_system_appid",
  "subMerchantNo": "your_sub_merchant_no",
  "bizContent": "{\"mobile\":\"13800138000\"}",
  "version": "1.0",
  "nonce": "49d55020fa3adf6ed67b253c583ccdaa",
  "contentHash": "hash_value",
  "timestamp": "2026-09-18 10:00:00",
  "sign": "your_sign"
}

号段查询：

json

{
  "appId": "your_system_appid",
  "subMerchantNo": "your_sub_merchant_no",
  "bizContent": "{\"mobile\":\"1380013\"}",
  "version": "1.0",
  "nonce": "49d55020fa3adf6ed67b253c583ccdaa",
  "contentHash": "hash_value",
  "timestamp": "2026-09-18 10:00:00",
  "sign": "your_sign"
}

响应参数

响应附加参数（data）

参数名	类型	必填	说明
`phone`	String	Y	号段（前7位），如 "1380013"
`province`	String	Y	省份，如 "北京"
`city`	String	Y	城市，如 "北京"
`isp`	String	Y	运营商，如 "中国移动"、"中国联通"、"中国电信"
`prefix`	String	N	号码前缀（前3位），如 "138"
`address`	String	Y	完整归属地地址，由省份+城市拼接而成，如 "北京北京"

响应示例

成功响应：

json

{
  "code": "0000",
  "message": "查询成功",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {
    "phone": "1380013",
    "province": "北京",
    "city": "北京",
    "isp": "中国移动",
    "prefix": "138",
    "address": "北京 北京"
  }
}

失败响应：

// 缺少手机号参数
{
  "code": "4003",
  "message": "缺少必填参数 mobile",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {}
}

// 手机号格式不正确
{
  "code": "4003",
  "message": "mobile 参数格式不正确，需为7位号段或11位手机号",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {}
}

// 未找到号段信息
{
  "code": "4003",
  "message": "未找到该号段信息",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {}
}

// 缺少业务参数
{
  "code": "4003",
  "message": "缺少业务参数",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {}
}

错误码说明

错误码	说明
`0000`	成功
`4003`	参数错误（缺少业务参数 / 缺少mobile参数 / 手机号格式不正确 / 未找到号段信息）
`5000`	系统异常

代码示例

JAVAPythonPHP

java

import java.util.HashMap;
import java.util.Map;
import com.alibaba.fastjson.JSON;

public class MobileQueryExample {
    public static void main(String[] args) {
        String appId = "your_app_id";
        String subMerchantNo = "your_sub_merchant_no";
        String signKey = "your_sign_key";
        String apiUrl = "https://openapi.shuhuipay.com/v1/query/mobile";

        // 构建 bizContent
        Map<String, String> bizContent = new HashMap<>();
        bizContent.put("mobile", "13800138000");

        Map<String, String> requestData = new HashMap<>();
        requestData.put("appId", appId);
        requestData.put("subMerchantNo", subMerchantNo);
        requestData.put("bizContent", JSON.toJSONString(bizContent));
        requestData.put("version", "1.0");
        requestData.put("nonce", "49d55020fa3adf6ed67b253c583ccdaa");
        requestData.put("contentHash", "hash_value");
        requestData.put("timestamp", "2026-09-18 10:00:00");

        String sign = SignUtil.generateSign(requestData, signKey);
        requestData.put("sign", sign);

        String response = HttpUtil.post(apiUrl, requestData);
        System.out.println("查询结果：" + response);
    }
}

Python

import requests
import json
import hashlib

def query_mobile_location(mobile):
    """查询手机号归属地"""
    sys_appid = "your_sys_appid"
    sub_merchant_no = "your_sub_merchant_no"
    sign_key = "your_sign_key"
    api_url = "https://openapi.shuhuipay.com/v1/query/mobile"

    # 构建 bizContent
    biz = {"mobile": mobile}

    request_data = {
        "appId": sys_appid,
        "subMerchantNo": sub_merchant_no,
        "version": "1.0",
        "timestamp": "2026-09-18 10:00:00",
        "nonce": "49d55020fa3adf6ed67b253c583ccdaa",
        "bizContent": json.dumps(biz),
        "contentHash": "hash_value",
    }

    sign = generate_sign(request_data, sign_key)
    request_data["sign"] = sign

    try:
        response = requests.post(api_url, json=request_data, timeout=30)
        return response.json()
    except Exception as e:
        print(f"查询失败: {e}")
        return None

def generate_sign(params, sign_key):
    sorted_params = sorted(params.items())
    sign_str = "&".join([f"{k}={v}" for k, v in sorted_params if v])
    sign_str += f"&key={sign_key}"
    return hashlib.md5(sign_str.encode()).hexdigest().upper()

# 查询手机号归属地
result = query_mobile_location("13800138000")

# 处理返回结果
if result and result.get("code") == "0000":
    data = result.get("data", {})
    print(f"归属地: {data.get('address')}")
    print(f"运营商: {data.get('isp')}")

php

<?php

class MobileQuery {
    private $appId = 'your_app_id';
    private $subMerchantNo = 'your_sub_merchant_no';
    private $signKey = 'your_sign_key';
    private $apiUrl = 'https://openapi.shuhuipay.com/v1/query/mobile';

    public function queryMobile($mobile) {
        // 构建 bizContent
        $bizContent = ['mobile' => $mobile];

        $requestData = [
            'appId'          => $this->appId,
            'subMerchantNo'  => $this->subMerchantNo,
            'bizContent'     => json_encode($bizContent),
            'version'        => '1.0',
            'nonce'          => '49d55020fa3adf6ed67b253c583ccdaa',
            'contentHash'    => 'hash_value',
            'timestamp'      => '2026-09-18 10:00:00',
        ];

        $requestData['sign'] = $this->generateSign($requestData);
        $response = $this->httpPost($this->apiUrl, $requestData);
        return json_decode($response, true);
    }

    private function generateSign($params) {
        ksort($params);
        $signStr = '';
        foreach ($params as $key => $value) {
            if ($value !== '') {
                $signStr .= "{$key}={$value}&";
            }
        }
        $signStr .= "key={$this->signKey}";
        return strtoupper(md5($signStr));
    }

    private function httpPost($url, $data) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }
}

// 查询手机号归属地
$result = (new MobileQuery())->queryMobile('13800138000');

// 处理返回结果
if ($result && $result['code'] === '0000') {
    $data = $result['data'] ?? [];
    echo "归属地: " . ($data['address'] ?? '') . PHP_EOL;
    echo "运营商: " . ($data['isp'] ?? '') . PHP_EOL;
}

注意事项

DANGER

🚫 参数限制：

mobile 为必填参数，不传将返回参数缺失错误
仅支持中国大陆手机号格式（1开头，第二位 3-9）
支持 11 位完整手机号或 7 位号段，其他长度将返回格式错误
传入 11 位手机号时系统自动截取前 7 位进行号段匹配

WARNING

⚠️ 查询说明：

该接口无需登录和权限验证，通过公共参数 appId 和 subMerchantNo 鉴权
基于手机号前7位号段数据库进行匹配查询
响应中的 address 字段为省份+城市的拼接结果
虚拟运营商号段同样支持查询

TIP

✅ 最佳实践：

推荐传入完整11位手机号，系统会自动处理号段截取
查询结果可缓存，号段归属地信息变更频率较低
注意处理号段未收录的情况，返回 "未找到该号段信息"

手机号归属地查询接口 ​

接口说明 ​

请求参数 ​

bizContent 业务参数 ​

请求示例 ​

响应参数 ​

响应附加参数（data） ​

响应示例 ​

错误码说明 ​

代码示例 ​

注意事项 ​

手机号归属地查询接口

接口说明

请求参数

bizContent 业务参数

请求示例

响应参数

响应附加参数（data）

响应示例

错误码说明

代码示例

注意事项