数汇联动API

Appearance

IP地址查询接口 ​

更新时间：2026-09-18

接口说明 ​

IP地址归属地查询接口，通过 bizContent 中的 ipv4 或 ipv6 参数查询IP归属地信息，包括国家、省份、城市、运营商等。

接口信息

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

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

WARNING

  • 该接口用于查询 IP 地址的归属地信息，支持 IPv4 和 IPv6
  • IPv4 和 IPv6 参数二选一，同时传入时优先使用 IPv4
  • 返回信息包含洲、国家、省份、城市、区县、运营商、经纬度等
  • 该接口无需登录，无需权限验证

请求参数 ​

bizContent 业务参数 ​

参数名类型必填参数说明
ipv4String二选一IPv4地址，如 8.8.8.8，与 ipv6 二选一
ipv6String二选一IPv6地址，如 2400:da00::1，与 ipv4 二选一

参数说明：

  • ipv4 和 ipv6 至少传入一个，否则将返回参数缺失错误
  • 同时传入 ipv4 和 ipv6 时，优先使用 ipv4
  • IP地址格式不合法时将返回参数格式错误

请求示例 ​

IPv4 查询：

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

IPv6 查询：

json
{
  "appId": "your_system_appid",
  "subMerchantNo": "your_sub_merchant_no",
  "bizContent": "{\"ipv6\":\"2400:da00::1\"}",
  "version": "1.0",
  "nonce": "49d55020fa3adf6ed67b253c583ccdaa",
  "contentHash": "hash_value",
  "timestamp": "2026-09-18 10:00:00",
  "sign": "your_sign"
}

响应参数 ​

响应附加参数（data） ​

参数名类型必填说明
addressStringY完整归属地地址，由洲+国家+省份+城市+区县拼接而成，如 "亚洲 中国 广东省 深圳市 南山区"
continentStringY所属洲，如 "亚洲"
countryStringY国家，如 "中国"
country_codeStringY国家代码，如 "CN"
provinceStringY省份，如 "广东省"
cityStringY城市，如 "深圳市"
districtStringY区县，如 "南山区"
ispStringY运营商，如 "Google LLC"
asnStringN自治系统号，如 "15169"
as_nameStringN自治系统名称，如 "GOOGLE"
as_domainStringN自治系统域名，如 "google.com"
geo_idStringN地理位置ID
longitudeStringN经度，如 "-97.822"
latitudeStringN纬度，如 "37.751"
timezoneStringN时区，如 "America/Chicago"
usage_typeStringNIP用途类型

响应示例 ​

成功响应：

json
{
  "code": "0000",
  "message": "查询成功",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {
    "continent": "北美洲",
    "country_code": "US",
    "country": "美国",
    "province": "加利福尼亚州",
    "city": "山景城",
    "district": "",
    "geo_id": 5375480,
    "longitude": "-122.084",
    "latitude": "37.386",
    "timezone": "America/Los_Angeles",
    "isp": "Google LLC",
    "asn": "15169",
    "as_name": "GOOGLE",
    "as_domain": "google.com",
    "usage_type": "Search Engine",
    "address": "北美洲 美国 加利福尼亚州 山景城 "
  }
}

失败响应：

jsoan
// 缺少IP参数
{
  "code": "4003",
  "message": "缺少IP参数，请传入 ipv4 或 ipv6",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {}
}

// IP格式不正确
{
  "code": "4003",
  "message": "ipv4 参数格式不正确",
  "timestamp": "2026-09-18T10:00:00.000Z",
  "data": {}
}

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

错误码说明 ​

错误码说明
0000成功
4003参数错误（缺少业务参数 / 缺少IP参数 / IP格式不正确）
5000系统异常

代码示例 ​

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

public class IpQueryExample {
    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/ip";

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

        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_ip_info(ipv4=None, ipv6=None):
    """查询IP地址归属地"""
    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/ip"

    # 构建 bizContent
    biz = {}
    if ipv4:
        biz["ipv4"] = ipv4
    if ipv6:
        biz["ipv6"] = ipv6

    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()

# 查询IPv4地址
result = query_ip_info(ipv4="8.8.8.8")

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

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

    public function queryIp($ipv4 = '', $ipv6 = '') {
        // 构建 bizContent
        $bizContent = [];
        if (!empty($ipv4)) {
            $bizContent['ipv4'] = $ipv4;
        }
        if (!empty($ipv6)) {
            $bizContent['ipv6'] = $ipv6;
        }

        $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;
    }
}

// 查询IPv4地址
$result = (new IpQuery())->queryIp('8.8.8.8');

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

注意事项 ​

DANGER

🚫 参数限制：

  • ipv4 和 ipv6 至少传入一个，否则将返回参数缺失错误
  • 同时传入两个参数时，优先使用 ipv4 进行查询
  • IP地址必须符合标准格式，否则返回格式校验错误

WARNING

⚠️ 查询说明：

  • 该接口无需登录和权限验证，通过公共参数 appId 和 subMerchantNo 鉴权
  • 使用内置IP地址库进行查询，返回归属地信息
  • 响应中的 address 字段为洲+国家+省份+城市+区县的拼接结果
  • 响应中不包含 cidr 字段

TIP

✅ 最佳实践：

  • 建议在调用前对IP地址做基础格式校验，减少无效请求
  • 查询结果可缓存，避免对同一IP地址频繁调用
  • 注意区分内网IP（如 192.168.x.x、10.x.x.x），此类IP可能无法查询到有效归属地