使用说明
IP 归属查询

接口参考

IP 归属查询

本页目录

查询 IPv4 / IPv6 的国家、省市区县、运营商、ASN、经纬度、时区与代理特征。返回结构遵循 统一响应格式。

接口

方法路径说明
GET/api/query查询调用方自己的出口 IP
POST/api/query查询指定 IP; 请求体省略或 ip 为空时回退为调用方 IP

请求体 (POST)

JSON
{ "ip": "8.8.8.8" }
字段类型说明
ipstring要查询的 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 / ipVersionIP 地址与版本 (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 / postalIANA 时区与邮编
registered_countryIP 注册国家: code / name
accuracy精度: high / medium / low
source数据来源: Merged-IP / GeoCN / MaxMind
traitsIP 特征标记, 只有命中代理记录时才出现, 见下文

country、province、city 等名称字段固定为中文, 不随请求语言变化。

traits 特征标记

字段说明
isProxy公开代理
isVPNVPN 出口
isTorTor 中继 / 出口
isHosting机房 / 云主机
isCDNCDN 节点
isSchool校园网
isAnonymous匿名网络 (如 iCloud Private Relay)

traits 缺失表示「没有记录」, 不等于确认是干净 IP; 需要判断调用方自身是否在走代理时用 代理检测。

私有地址

RFC 1918、CGNAT (100.64.0.0/10)、链路本地、回环等保留地址不查库, 直接返回 country 为「私有网络」、countryCode 为 PRIVATE 的固定结果。

错误

code场景
400ip 格式无效, 或无法识别调用方 IP
429超过 600 次 / 分钟, 见 限速
500查询失败

成功响应带 Cache-Control: public, max-age=300, 批量查询时请按 IP 在本地缓存。