IP地址详情V2-街道级接口文档

接口说明

一款高精度 IP 归属地查询接口，支持 IPv4 和 IPv6 双栈查询，可精确到街道级别。本接口为免费调用，适用于需要获取 IP 地址详细地理位置信息的业务场景。

调用地址

https://api.xunjinlu.fun/api/ip/v2.php

请求方式

• GET
• POST

鉴权方式

本接口支持以下三种鉴权方式，调用方需至少使用其中一种：

1. Query 参数鉴权：在 URL 查询字符串中传递 key 参数
2. Header 鉴权：在请求头中设置 X-API-Key
3. Bearer Token 鉴权：在请求头中设置 Authorization: Bearer

请求参数

参数说明

• key：您的接口访问密钥，用于身份验证和计费统计。请妥善保管，避免泄露。
• ip：需要查询归属地的 IP 地址，支持 IPv4 和 IPv6 格式。

请求示例

示例 1：Query 参数鉴权（GET）

GET https://api.xunjinlu.fun/api/ip/v2.php?key=sk_xxxxxxxxxxxxxxxx&ip=114.88.43.167

示例 2：Header 鉴权（GET）

GET https://api.xunjinlu.fun/api/ip/v2.php?ip=114.88.43.167
X-API-Key: sk_xxxxxxxxxxxxxxxx

示例 3：Bearer Token 鉴权（POST）

POST https://api.xunjinlu.fun/api/ip/v2.php
Authorization: Bearer sk_xxxxxxxxxxxxxxxx
Content-Type: application/x-www-form-urlencoded

ip=114.88.43.167

成功响应示例

{
    "code": 0,
    "msg": "查询成功",
    "time": "2026-05-25 04:30:00",
    "data": {
        "ip": "114.88.43.167",
        "isp": "电信",
        "country": "中国",
        "continent": "亚洲",
        "province": "上海市",
        "city": "上海市",
        "district": "浦东新区",
        "street": "陆家嘴街道",
        "latitude": "31.24",
        "longitude": "121.50",
        "full_address": "电信亚洲中国上海市上海市浦东新区陆家嘴街道(lat31.24/lon121.50)"
    },
    "api_info": {
        "developer": "尋鯨錄",
        "blog": "https://www.xunjinlu.fun",
        "api_platform": "https://api.xunjinlu.fun"
    }
}

响应字段说明

顶层字段

data 字段说明

api_info 字段说明

错误响应示例

未提供密钥

{
    "code": 0,
    "msg": "未提供密钥",
    "errcode": 11001
}

密钥错误

{
    "code": 0,
    "msg": "密钥错误",
    "errcode": 11002
}

密钥已禁用

{
    "code": 0,
    "msg": "密钥已禁用",
    "errcode": 11003
}

积分不足

{
    "code": 0,
    "msg": "积分不足",
    "errcode": 11004
}

请求过于频繁

{
    "code": 0,
    "msg": "请求过于频繁",
    "errcode": 11005
}

维护中

{
    "code": 0,
    "msg": "维护中",
    "errcode": 11006
}

接口已禁用

{
    "code": 0,
    "msg": "接口已禁用",
    "errcode": 11007
}

鉴权方式错误

{
    "code": 0,
    "msg": "鉴权方式错误",
    "errcode": 11012
}

业务错误码说明

频率限制

• 每分钟约 50 次请求

调用示例

PHP 示例

// IP地址详情V2-街道级接口调用示例

$key = 'sk_xxxxxxxxxxxxxxxx';
$ip = '114.88.43.167';

// 方式1：Query 参数鉴权
$url = "https://api.xunjinlu.fun/api/ip/v2.php?key={$key}&ip={$ip}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] === 0) {
    echo "IP: " . $result['data']['ip'] . "\n";
    echo "地址: " . $result['data']['full_address'] . "\n";
} else {
    echo "错误: " . $result['msg'] . "\n";
}

// 方式2：Header 鉴权
$url = "https://api.xunjinlu.fun/api/ip/v2.php?ip={$ip}";
$headers = [
    "X-API-Key: {$key}"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

// 方式3：Bearer Token 鉴权
$headers = [
    "Authorization: Bearer {$key}"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

JavaScript 示例

// IP地址详情V2-街道级接口调用示例

const key = 'sk_xxxxxxxxxxxxxxxx';
const ip = '114.88.43.167';

// 方式1：Query 参数鉴权
fetch(`https://api.xunjinlu.fun/api/ip/v2.php?key=${key}&ip=${ip}`)
    .then(response => response.json())
    .then(data => {
        if (data.code === 0) {
            console.log('IP:', data.data.ip);
            console.log('地址:', data.data.full_address);
        } else {
            console.error('错误:', data.msg);
        }
    });

// 方式2：Header 鉴权
fetch(`https://api.xunjinlu.fun/api/ip/v2.php?ip=${ip}`, {
    headers: {
        'X-API-Key': key
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

// 方式3：Bearer Token 鉴权
fetch(`https://api.xunjinlu.fun/api/ip/v2.php?ip=${ip}`, {
    headers: {
        'Authorization': `Bearer ${key}`
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

Python 示例

# IP地址详情V2-街道级接口调用示例

import requests

key = 'sk_xxxxxxxxxxxxxxxx'
ip = '114.88.43.167'

# 方式1：Query 参数鉴权
url = f'https://api.xunjinlu.fun/api/ip/v2.php?key={key}&ip={ip}'
response = requests.get(url)
data = response.json()

if data['code'] == 0:
    print(f"IP: {data['data']['ip']}")
    print(f"地址: {data['data']['full_address']}")
else:
    print(f"错误: {data['msg']}")

# 方式2：Header 鉴权
url = f'https://api.xunjinlu.fun/api/ip/v2.php?ip={ip}'
headers = {'X-API-Key': key}
response = requests.get(url, headers=headers)

# 方式3：Bearer Token 鉴权
headers = {'Authorization': f'Bearer {key}'}
response = requests.get(url, headers=headers)

注意事项

1. 请确保您的密钥有效且未过期
2. 本接口为免费调用，但仍需进行身份验证
3. 请遵守频率限制，避免因请求过于频繁而被限制访问
4. 返回的经纬度信息为字符串格式，如需数值计算请自行转换
5. 如遇网络问题，建议实现重试机制，但需控制重试间隔