# IP 归属查询

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

## 接口

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

### 请求体 (POST)

```json
{ "ip": "8.8.8.8" }
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `ip` | string | 要查询的 IPv4 或 IPv6 地址; 格式无效时返回 `400` |

### 请求示例

```bash
# 查询自己
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; 需要判断调用方自身是否在走代理时用 [代理检测](/docs/proxy-detection)。

### 私有地址

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

## 错误

| code | 场景 |
| --- | --- |
| `400` | `ip` 格式无效, 或无法识别调用方 IP |
| `429` | 超过 600 次 / 分钟, 见 [限速](/docs/conventions#限速) |
| `500` | 查询失败 |

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