API 文档 - IP2Address

概述

IP2Address 是一个基于 ip2region 的 IP 地址归属地查询服务，同时支持 IPv4 和 IPv6 地址定位查询。

单文件部署：所有数据嵌入二进制文件
双版本支持：同时支持 IPv4 和 IPv6
多格式输出：JSON、XML、Text
域名解析：支持输入域名自动解析后查询

API 接口

查询客户端 IP

GET /ip

返回客户端自身的 IP 地址及归属地信息

curl "https://ip.020028.xyz/ip?format=json"

响应示例：

{"ip":"8.8.8.8","region":"United States|California|0|Google LLC|US","found":true}

查询指定 IP

GET /ip/{address}

查询指定 IPv4 或 IPv6 地址的归属地

# IPv4 查询
curl "https://ip.020028.xyz/ip/8.8.8.8?format=json"

# IPv6 查询
curl "https://ip.020028.xyz/ip/240e:3b7:3272:d8d0:db09:c067:8d59:539e?format=json"

域名解析查询

GET /lookup?q={domain_or_ip}

解析域名获取所有 IP 地址，并查询每个 IP 的归属地。也支持直接输入 IP 地址。

# 域名查询
curl "https://ip.020028.xyz/lookup?q=google.com"

# IP 查询（与 /ip 接口等效，但返回格式不同）
curl "https://ip.020028.xyz/lookup?q=8.8.8.8"

响应示例（域名查询）：

{
  "query>{
  "query": "google.com",
  "results": [
    {"ip":"142.250.80.46","region":"United States|California|0|Google LLC|US","found":true},
    {"ip":"2404:6800:4008:c15::71","region":"...","found":true}
  ]
}

获取客户端 IP

GET /myip

轻量级接口，仅返回客户端 IP 地址（JSON 格式）

curl "https://ip.020028.xyz/myip"

响应示例：

{"ip":"8.8.8.8"}

查询参数

参数	说明	适用接口	默认值
`format`	响应格式：json / xml / text	/ip, /ip/{addr}	json
`token`	认证 Token	所有接口	无
`q`	查询内容（IP 或域名）	/lookup	必填

💡 Token 也可通过 HTTP Header X-Token 传递。

响应格式

JSON

{"ip":"8.8.8.8","region":"United States|California|0|Google LLC|US","found":true}

XML

<?xml version="1.0" encoding="UTF-8"?>
<IPInfo><ip>8.8.8.8</ip><region>United States|California|0|Google LLC|US</region><found>true</found></IPInfo>

Text

8.8.8.8|United States|California|0|Google LLC|US

认证与限流

Token 认证

如果服务端配置了 Token，则请求时需携带有效 Token：

# 通过查询参数
curl "https://ip.020028.xyz/ip/8.8.8.8?token=YOUR_TOKEN"

# 通过 Header
curl -H "X-Token: YOUR_TOKEN" "https://ip.020028.xyz/ip/8.8.8.8"

限流规则

请求类型	限制
无 Token 请求	全局每分钟 600 次
有效 Token 请求	无限制

超过限流时返回 HTTP 429 状态码。

Region 字段格式

Region 字段使用 | 分隔，格式为：

国家|省份|城市|运营商|国家代码

示例：

中国|广东省|深圳市|电信|CN
United States|California|0|Google LLC|US

部分字段可能为 0，表示该信息不可用。

命令行参数

参数	说明	默认值
`-server`	监听地址	:8080
`-token`	认证 Token	空（不验证）
`-format`	默认响应格式	text
`-start`	以 Daemon 启动	-
`-stop`	停止 Daemon	-
`-restart`	重启 Daemon	-