接口参考
IP 归属查询
查询 IPv4 / IPv6 的国家、省市区县、运营商、ASN、经纬度、时区与代理特征。返回结构遵循 统一响应格式。
接口
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/query | 查询调用方自己的出口 IP |
POST | /api/query | 查询指定 IP; 请求体省略或 ip 为空时回退为调用方 IP |
请求体 (POST)
JSON
{ "ip": "8.8.8.8" }| 字段 | 类型 | 说明 |
|---|---|---|
ip | string | 要查询的 IPv4 或 IPv6 地址; 格式无效时返回 400 |
请求示例
Shell
# 查询自己
curl https://ip.czl.net/api/query
# 查询指定 IP
curl -X POST https://ip.czl.net/api/query \
-H "Content-Type: application/json" \
-d '{"ip": "8.8.8.8"}'JavaScript
const res = await fetch("https://ip.czl.net/api/query", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ip: "8.8.8.8" }),
});
const { code, data, msg } = await res.json();
if (code !== 200) throw new Error(`ip query failed: ${code} ${msg}`);
console.log(data.country, data.city, data.isp);响应示例
JSON
{
"code": 200,
"data": {
"ip": "8.8.8.8",
"ipVersion": "IPv4",
"country": "美国",
"countryCode": "US",
"province": "加利福尼亚州",
"city": "山景城",
"isp": "Google LLC",
"as": { "number": 15169, "name": "GOOGLE", "info": "Google LLC" },
"addr": "美国 加利福尼亚州 山景城",
"regions": ["美国", "加利福尼亚州", "山景城"],
"location": { "latitude": 37.4056, "longitude": -122.0775, "accuracy_radius": 1000 },
"timezone": "America/Los_Angeles",
"postal": "94043",
"registered_country": { "code": "US", "name": "美国" },
"accuracy": "medium",
"source": "Merged-IP"
},
"msg": "success"
}字段说明
| 字段 | 说明 |
|---|---|
ip / ipVersion | IP 地址与版本 (IPv4 / IPv6) |
country / countryCode | 国家名 (中文) 与 ISO 3166-1 国家码 |
province / city / district | 省 / 市 / 区县, 以及对应的 provinceCode / cityCode / districtCode, 按数据可得性出现 |
isp / net | 运营商与网络类型 |
as | 自治系统: number (ASN 号) / name / info |
addr / regions / regions_short | 拼接后的完整地址串, 以及省市区数组 |
location | 坐标 (WGS-84): latitude / longitude / accuracy_radius (公里) |
timezone / postal | IANA 时区与邮编 |
registered_country | IP 注册国家: code / name |
accuracy | 精度: high / medium / low |
source | 数据来源: Merged-IP / GeoCN / MaxMind |
traits | IP 特征标记, 只有命中代理记录时才出现, 见下文 |
country、province、city 等名称字段固定为中文, 不随请求语言变化。
traits 特征标记
| 字段 | 说明 |
|---|---|
isProxy | 公开代理 |
isVPN | VPN 出口 |
isTor | Tor 中继 / 出口 |
isHosting | 机房 / 云主机 |
isCDN | CDN 节点 |
isSchool | 校园网 |
isAnonymous | 匿名网络 (如 iCloud Private Relay) |
traits缺失表示「没有记录」, 不等于确认是干净 IP; 需要判断调用方自身是否在走代理时用 代理检测。
私有地址
RFC 1918、CGNAT (100.64.0.0/10)、链路本地、回环等保留地址不查库, 直接返回 country 为「私有网络」、countryCode 为 PRIVATE 的固定结果。
错误
| code | 场景 |
|---|---|
400 | ip 格式无效, 或无法识别调用方 IP |
429 | 超过 600 次 / 分钟, 见 限速 |
500 | 查询失败 |
成功响应带 Cache-Control: public, max-age=300, 批量查询时请按 IP 在本地缓存。