注意两点：① 接口 HTTP 状态码恒为 200，成功失败一律看返回 JSON 的 code字段（200 即成功）；② 请求需携带浏览器风格 UA，否则返回 code=403（下方示例均已处理）。
一、快速调用
免费 IP 归属地查询接口：传 ip 查指定 IP 的归属地，不传则返回本机公网 IP。无需注册、无需 Key，复制即用。
# 查询指定 IP
https://xxkx.net/api/ip_api.php?ip=1.1.1.1
# 不传参数 = 获取本机出口公网 IP
https://xxkx.net/api/ip_api.php
二、接口信息
| 接口地址 | https://xxkx.net/api/ip_api.php |
| 请求方式 | GET，支持跨域 |
| 数据格式 | JSON（UTF-8） |
| 支持类型 | IPv4 / IPv6 |
| 计费方式 | 免费，无需注册 / Key |
| 数据缓存 | 相同 IP 结果缓存 48 小时（命中同样计入调用次数） |
三、请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|
| ip |
可选 |
string |
要查询的 IP（IPv4/IPv6），格式非法返回 code=400 不传则默认返回本机公网 IP。 |
旧版 ?myip=1 写法兼容，仍返回本机 IP。
四、返回结果
顶层字段：code（状态码）、data（归属地数据）、query_time（耗时秒）、api_from（来源）；失败时带 msg。
{
"code": 200,
"data": {
"ip": "123.161.168.147",
"country": "中国",
"prov": "河南",
"city": "驻马店",
"area": "平舆",
"isp": "中国电信",
"lng": "114.64",
"lat": "32.96",
"long_ip": 2074192019,
"big_area": "华中",
"ip_type": "ISP",
"ip_asn": "AS4134"
},
"query_time": 0.001,
"api_from": "xxkx.net免费ip查询接口"
}
data 字段说明
| 字段 | 类型 | 说明 |
|---|
| ip | string | 查询的 IP 地址 |
| country | string | 国家/地区名称 |
| country_code | string | 国家代码（如 cn） |
| prov | string | 省份 |
| city | string | 城市 |
| city_code | string | 城市代码（拼音） |
| city_short_code | string | 城市简称代码 |
| area | string | 区县（部分 IP 可能为空） |
| post_code | string | 邮政编码（IPv6 查询可能为空） |
| area_code | string | 电话区号（IPv6 查询可能为空） |
| isp | string | 运营商（如 中国电信） |
| lng | string | 经度 |
| lat | string | 纬度 |
| long_ip | int | IP 的十进制整数表示 |
| big_area | string | 地理大区（如 华中） |
| ip_type | string | IP 类型（如 ISP） |
| ip_asn | string | ASN 编号（如 AS4134） |
五、代码示例
1. curl
# 必须用 -A 指定浏览器UA，否则返回 403
curl -A 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' 'https://xxkx.net/api/ip_api.php?ip=1.1.1.1'
# 空请求 = 获取本机出口公网 IP
curl -A 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' 'https://xxkx.net/api/ip_api.php'
2. PHP
function xxkx_query($ip) {
$url = 'https://xxkx.net/api/ip_api.php?ip=' . urlencode($ip);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_USERAGENT => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36', // 必须带浏览器UA
]);
$body = curl_exec($ch);
curl_close($ch);
return json_decode($body, true); // code=-1 需自行处理网络/解析错误
}
$ret = xxkx_query('1.1.1.1');
if (isset($ret['code']) && $ret['code'] === 200) {
echo '查询成功：' . $ret['data']['prov'] . $ret['data']['city'] . ' ' . $ret['data']['isp'] . PHP_EOL;
} else {
echo '查询失败 code=' . ($ret['code'] ?? '?') . ' msg=' . ($ret['msg'] ?? '未知错误') . PHP_EOL;
}
3. JavaScript
浏览器请求自动携带浏览器 UA，直接 fetch 即可。
async function queryIp(ip) {
const res = await fetch('https://xxkx.net/api/ip_api.php?ip=' + encodeURIComponent(ip));
const data = await res.json();
if (data.code !== 200) throw new Error('[' + data.code + '] ' + (data.msg || ''));
return data.data;
}
queryIp('1.1.1.1').then(d => console.log('查询成功：', d.prov, d.city, d.isp));
4. Python
import requests
def query_ip(ip):
r = requests.get('https://ixxkx.net/api/ip_api.php', params={'ip': ip}, headers={
'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' # 必须带浏览器UA
}, timeout=10)
d = r.json() # HTTP恒为200，用 code 判断成败
if d.get('code') == 200:
return d['data']
raise Exception('[' + str(d.get('code')) + '] ' + str(d.get('msg')))
print('查询成功：', query_ip('1.1.1.1'))
六、状态码 / 频率限制 / 常见问题
状态码
| code | 含义 | 处理 |
|---|
| 200 | 查询成功 | 直接取 data 使用 |
| 400 | ip 参数不是合法 IPv4/IPv6 | 检查参数格式 |
| 403 | UA 被拦截 / IP 被封禁 | 检查是否带浏览器 UA |
| 429 | 请求超频（见下） | 降速后重试 |
| 500 | 上游接口异常 | 稍后重试，无需改代码 |
频率限制
| 规则 | 说明 |
|---|
| 60 秒长窗口 | 单 IP 60 秒内最多 100 次 |
| 1 秒脉冲窗口 | 单 IP 1 秒内最多 5 次（瞬时并发勿超 5） |
| 阶梯封禁 | 5 分钟 ≥3 次限流 → 封 15 分钟；1 小时 ≥6 次 → 封 60 分钟；24 小时 ≥12 次 → 永久拉黑 |
| 白名单 | 白名单 IP 不受限流与封禁影响 |
建议：正常业务调用间隔 ≥1 秒；批量查询请加延时或队列，避免触发封禁。
常见问题
| 问题 | 原因 & 解决 |
|---|
| curl / 代码调用返回 403？ | 没带浏览器 UA。用 -A 或代码里设置 UA 即可（见第五节）。 |
| 返回 429？ | 请求太频繁。60 秒 ≤60 次、1 秒 ≤5 次，降速重试；多次触发会被临时封禁（403）。 |
| 查询 IPv6 邮编、区号为空？ | 正常。IPv6 上游数据部分字段为空，以实际返回为准。 |
| 需要注册或 Key 吗？ | 不需要。免费直接调用。 |
七、版本记录
| v1.0 | 2026-09-01 | 初版：接口简化（取消 myip 参数，空请求返回本机 IP，兼容 ?myip=1），文档精简为快速调用版。 |