IP归属地查询API
接口说明
IP归属地查询API用于查询任意IP地址的地理位置信息,包括国家、省份、城市、运营商等详细信息。支持IPv4和IPv6地址查询。
请求方式
GET
接口地址
/api/ip/query
返回格式
JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
ip |
string | 是 | 要查询的IP地址,支持IPv4和IPv6 |
key |
string | 是 | 您的API密钥 |
salt |
string | 否 | 自定义随机字符串,用于签名验证 |
format |
string | 否 | 返回格式,默认json,也可指定xml |
请求示例
Shell
curl -X GET "https://api.mingmingjieshuo.com.cn/api/ip/query?ip=8.8.8.8&key=YOUR_API_KEY"
返回结果
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
code |
int | 状态码,200表示成功 |
message |
string | 返回信息 |
data |
object | 归属地信息对象 |
data.ip |
string | 查询的IP地址 |
data.country |
string | 国家/地区 |
data.province |
string | 省份/州 |
data.city |
string | 城市 |
data.district |
string | 区/县 |
data.isp |
string | 运营商 |
data.latitude |
float | 纬度 |
data.longitude |
float | 经度 |
返回示例
JSON
XML
{
"code": 200,
"message": "success",
"data": {
"ip": "8.8.8.8",
"country": "美国",
"province": "加利福尼亚州",
"city": "山景城",
"district": "",
"isp": "Google LLC",
"latitude": 37.4056,
"longitude": -122.0775,
"timezone": "America/Los_Angeles"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>200</code>
<message>success</message>
<data>
<ip>8.8.8.8</ip>
<country>美国</country>
<province>加利福尼亚州</province>
<city>山景城</city>
<isp>Google LLC</isp>
</data>
</response>
错误码
| 错误码 | 说明 | 解决方案 |
|---|---|---|
400 |
请求参数错误 | 检查IP格式是否正确 |
401 |
API密钥无效 | 检查API密钥是否正确 |
403 |
额度不足 | 前往充值 |
429 |
请求过于频繁 | 降低请求频率或升级套餐 |
500 |
服务器内部错误 | 稍后重试或联系技术支持 |
代码示例
JavaScript
Python
PHP
Java
JavaScript
// 使用 fetch 调用 IP归属地API
async function queryIPLocation(ip, apiKey) {
try {
const response = await fetch(
`https://api.mingmingjieshuo.com.cn/api/ip/query?ip=${ip}&key=${apiKey}`
);
const result = await response.json();
if (result.code === 200) {
const { country, province, city, isp } = result.data;
console.log(`${ip} 归属地: ${country} ${province} ${city} (${isp})`);
return result.data;
} else {
console.error('查询失败:', result.message);
}
} catch (error) {
console.error('请求错误:', error);
}
}
// 调用示例
queryIPLocation('8.8.8.8', 'YOUR_API_KEY');
Python
import requests
def query_ip_location(ip, api_key):
"""
查询IP归属地
"""
url = "https://api.mingmingjieshuo.com.cn/api/ip/query"
params = {
"ip": ip,
"key": api_key
}
try:
response = requests.get(url, params=params)
result = response.json()
if result["code"] == 200:
data = result["data"]
location = f"{data['country']} {data['province']} {data['city']}"
print(f"{ip} 归属地: {location} ({data['isp']})")
return data
else:
print(f"查询失败: {result['message']}")
return None
except Exception as e:
print(f"请求错误: {e}")
return None
# 调用示例
result = query_ip_location("8.8.8.8", "YOUR_API_KEY")
PHP
<?php
function queryIPLocation($ip, $apiKey) {
$url = "https://api.mingmingjieshuo.com.cn/api/ip/query";
$params = ['ip' => $ip, 'key' => $apiKey];
$url = $url . '?' . http_build_query($params);
try {
$response = file_get_contents($url);
$result = json_decode($response, true);
if ($result['code'] === 200) {
$data = $result['data'];
$location = "{$data['country']} {$data['province']} {$data['city']}";
echo "{$ip} 归属地: {$location} ({$data['isp']})\n";
return $data;
} else {
echo "查询失败: {$result['message']}\n";
return null;
}
} catch (Exception $e) {
echo "请求错误: {$e->getMessage()}\n";
return null;
}
}
// 调用示例
$result = queryIPLocation('8.8.8.8', 'YOUR_API_KEY');
?>
Java
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class IPLocationUtil {
public static String queryLocation(String ip, String apiKey) throws Exception {
String urlStr = "https://api.mingmingjieshuo.com.cn/api/ip/query?ip=" + ip + "&key=" + apiKey;
URL url = new URL(urlStr);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
BufferedReader reader = new BufferedReader(
new InputStreamReader(conn.getInputStream())
);
StringBuilder response = new StringBuilder();
String line;
while ((line = reader.readLine()) != null) {
response.append(line);
}
reader.close();
return response.toString();
}
public static void main(String[] args) {
try {
String result = queryLocation("8.8.8.8", "YOUR_API_KEY");
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
}
}
签名算法
安全提示
为保证接口安全性,建议使用签名方式验证。签名密钥请勿在客户端代码中暴露。
签名生成步骤
- 将所有请求参数(除sign外)按参数名的字母顺序排序
- 将参数名和参数值用
=连接,多个参数用&连接 - 在拼接好的字符串末尾追加签名密钥
- 使用 MD5 或 SHA256 对结果进行哈希运算
签名示例代码
JavaScript
// Node.js 签名示例
const crypto = require('crypto');
function generateSignature(params, secretKey) {
// 1. 排序参数
const sortedKeys = Object.keys(params).sort();
// 2. 拼接参数字符串
const paramString = sortedKeys
.map(key => `${key}=${params[key]}`)
.join('&');
// 3. 追加密钥并计算MD5
const signString = paramString + secretKey;
const signature = crypto
.createHash('md5')
.update(signString)
.digest('hex');
return signature;
}
// 使用示例
const params = {
ip: '8.8.8.8',
key: 'YOUR_API_KEY',
timestamp: Math.floor(Date.now() / 1000)
};
const signature = generateSignature(params, 'YOUR_SECRET_KEY');
console.log('签名:', signature);
注意事项
频率限制
免费用户每秒最多10次请求,付费用户可提升至每秒100次。建议添加请求间隔或实现本地缓存。
- 数据更新:IP归属地数据每日更新,部分新分配IP可能存在延迟
- IPv6支持:完全支持IPv6地址查询
- 缓存建议:相同IP查询结果建议缓存30分钟以上
- 隐私保护:请遵守当地法律法规,不要用于非法用途