很COOL的IP地理位置查询API

🚀 在线测试

📍 地理位置信息

查询后将在此显示易读的地理位置信息

📄 JSON响应

点击查询按钮开始测试...

✨ 功能特性

🎯 高精度定位

支持全球IP地理位置查询，中国大陆精确到区县级别

⚡ 高性能缓存

内置智能缓存机制，响应速度快，减少重复查询

🔒 安全稳定

支持CORS跨域，内置限流保护，确保服务稳定

📊 丰富数据

提供地理位置、ISP、ASN、时区等30+字段信息

📖 API文档

查询IP地理位置信息

GET OPTIONS

https://ipapi.zhouyang.cool/json/{ip}

描述：查询指定IP地址的地理位置信息

支持方法：GET（数据查询）、OPTIONS（CORS预检请求）

请求参数

参数名	类型	必填	说明	示例
ip	string	否	要查询的IP地址，留空则查询请求者IP	8.8.8.8
fields	string	否	指定返回字段，用逗号分隔	ip,country,city

请求示例

📍 查询指定IP地址

GET /json/8.8.8.8

查询Google DNS服务器的地理位置信息

🔍 查询当前请求者IP

GET /json/

自动检测并查询当前请求来源的IP地址

🎯 指定返回字段

GET /json/8.8.8.8?fields=ip,country,city,latitude,longitude

只返回指定的字段，减少响应数据量

🔒 IP获取安全说明

系统按以下优先级获取客户端IP地址：

URL路径参数 - 最高优先级，直接指定IP
query参数 - ?query=IP形式
X-Forwarded-For头 - 代理/负载均衡器设置
X-Real-IP头 - 反向代理设置
RemoteAddr - TCP连接的真实IP

⚠️ 注意：X-Forwarded-For和X-Real-IP头可能被客户端伪造，在生产环境中应配置可信的代理服务器。

响应字段说明

字段名	类型	说明	示例
ip	string	IP地址	"8.8.8.8"
network	string	网络段	"8.8.8.0/24"
version	string	IP版本	"IPv4"
city	string	城市	"山景城"
region	string	省份/州	"加利福尼亚州"
region_code	string	省份代码	"CA"
country	string	国家代码	"US"
country_name	string	国家名称	"美国"
country_code	string	国家代码(ISO)	"US"
country_code_iso3	string	国家代码(ISO3)	"USA"
country_capital	string	首都	"华盛顿"
country_tld	string	国家顶级域名	".us"
continent_code	string	大洲代码	"NA"
in_eu	bool	是否在欧盟	false
postal	string	邮政编码	"94043"
latitude	float64	纬度	37.4056
longitude	float64	经度	-122.0775
timezone	string	时区	"America/Los_Angeles"
country_calling_code	string	国际电话区号	"+1"
currency	string	货币代码	"USD"
currency_name	string	货币名称	"Dollar"
languages	string	语言代码	"en"
country_area	float64	国家面积(平方公里)	9629091
country_population	uint64	国家人口	327167434
asn	string	ASN号码	"AS15169"
org	string	组织名称	"Google LLC"
isp	string	ISP提供商	"Google"
city_code	uint	城市代码(GeoCN)	100100
districts	string	区县(GeoCN)	"海淀区"

HTTP状态码说明

状态码	说明	响应示例
200 OK	查询成功，返回IP地理位置信息	正常的JSON数据
200 OK	IP地址为私有地址	{"ip": "192.168.1.1", "message": "private range"}
200 OK	IP地址为保留地址	{"ip": "127.0.0.1", "message": "reserved range"}
200 OK	IP地址不在数据库中	{"ip": "1.2.3.4", "message": "not in database"}
400 Bad Request	IP地址格式无效	{"ip": "invalid.ip", "message": "invalid query"}
429 Too Many Requests	请求频率超过限制	Too Many Requests
500 Internal Server Error	服务器内部错误	{"ip": "8.8.8.8", "message": "internal error"}

成功响应示例

{
  "ip": "8.8.8.8",
  "network": "8.8.8.0/24",
  "version": "IPv4",
  "city": "山景城",
  "region": "加利福尼亚州",
  "region_code": "CA",
  "country": "US",
  "country_name": "美国",
  "country_code": "US",
  "country_code_iso3": "USA",
  "country_capital": "华盛顿",
  "country_tld": ".us",
  "continent_code": "NA",
  "in_eu": false,
  "postal": "94043",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "timezone": "America/Los_Angeles",
  "country_calling_code": "+1",
  "currency": "USD",
  "currency_name": "Dollar",
  "languages": "en",
  "country_area": 9629091,
  "country_population": 327167434,
  "asn": "AS15169",
  "org": "Google LLC"
}
            

错误响应示例

# 无效IP地址 (400 Bad Request)
{
  "ip": "invalid.ip.address",
  "message": "invalid query"
}

# 私有IP地址 (200 OK)
{
  "ip": "192.168.1.1",
  "message": "private range"
}

# 保留IP地址 (200 OK)
{
  "ip": "127.0.0.1",
  "message": "reserved range"
}

# IP不在数据库中 (200 OK)
{
  "ip": "1.2.3.4",
  "message": "not in database"
}
            

💡 使用示例

JavaScript (Fetch API)

// 查询指定IP
fetch('/json/8.8.8.8')
  .then(response => response.json())
  .then(data => console.log(data));

// 查询当前IP
fetch('/json/')
  .then(response => response.json())
  .then(data => console.log(data));
            

Python (requests)

import requests

# 查询指定IP
response = requests.get('https://ipapi.zhouyang.cool/json/8.8.8.8')
data = response.json()
print(data)

# 只获取特定字段
response = requests.get('https://ipapi.zhouyang.cool/json/8.8.8.8?fields=ip,country,city')
data = response.json()
print(data)
            

cURL

# 查询指定IP
curl https://ipapi.zhouyang.cool/json/8.8.8.8

# 查询当前IP
curl https://ipapi.zhouyang.cool/json/

# 指定返回字段
curl "https://ipapi.zhouyang.cool/json/8.8.8.8?fields=ip,country,city,latitude,longitude"
            

🌍 IP地理位置查询API