IP 查询 API 文档

接口使用 GET，返回 JSON。示例地址用于演示请求格式，实际结果以响应为准。

GET /api/check/lookup

curl 'https://ipcheak.com/api/check/lookup?ip=8.8.8.8'

可选参数 ip 接收单个公网 IPv4 或 IPv6。省略参数时解析调用方连接的公网出口；服务端调用会返回服务器出口，而不是最终用户的浏览器 IP。拒绝私网、保留地址和重复的 ip 参数。

字段	说明
`ip, ipVersion, source`	查询地址、4 / 6 版本及地址来源。
`requestId, observedAt`	请求标识与 ISO 8601 观测时间。
`network`	asn、name、domain、type、prefix、registeredCountry、asnHistory；部分字段可为 null。
`geo`	国家、地区、城市、时区及近似经纬度；不可用坐标为 null。
`signals`	proxy、vpn、tor、hosting、residentialProxy，取值 low / medium / high / unknown。
`confidence, providers`	总体证据可信度与各来源的状态、观测时间和具体字段。
`risk_score, risk_level, riskAnalysis`	风险分数（可为 null）、风险区间与组成证据。不是匿名性或安全保证。

GET /api/v1/ip/self

curl 'https://ipcheak.com/api/v1/ip/self'

查询调用方出口的精简响应：requestId、observedAt、ip、version、network、geo、signals、confidence 和 providers。此接口使用 version 字段，不包含完整查询接口的 riskAnalysis。

从服务端调用

const response = await fetch(
  'https://ipcheak.com/api/check/lookup?ip=8.8.8.8'
)
if (response.status === 429 || response.status === 503) {
  const seconds = response.headers.get('Retry-After')
  throw new Error(`Retry after ${seconds || '30'} seconds`)
}
if (!response.ok) throw new Error(`HTTP ${response.status}`)
const result = await response.json()
console.log(result.ip, result.network.asn, result.signals.vpn)

两个接口均未启用跨域浏览器访问。请处理非 2xx 响应、请求超时、缺失字段和上游来源限流；不要把 unknown 转换为 false。

频率与额度

默认同一调用方在高成本接口间共享每 60 秒 10 次、每 24 小时 100 次额度，包括 lookup、self 与扫描/诊断的高成本步骤。所有 API 另有每分钟 120 次、每天 2,000 次的调用方限制。IPv6 按 /64 网段合并计数；更换查询目标 IP 不会重置额度。窗口从首次请求起算，部署配置可调整这些默认值。

查询还受全站预算和并发上限约束。达到任一额度返回 429；服务繁忙或配额服务不可用返回 503。按 Retry-After 指定的秒数等待，不要立即重试或并发重试。成功响应的 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 表示当前调用方的分钟窗口，不能据此推断全站剩余额度。缓存命中仍计入调用方额度，但不重复消耗上游查询预算。

错误与信号语义

400 — ip 参数重复，单次仅接受一个地址。
422 — 地址无效、为非公网地址，或无法解析有效公网出口。
413 — 请求体超过 16 KiB。
429 — 调用频率或额度耗尽，按 Retry-After 等待。
503 — 服务繁忙或配额服务不可用，按 Retry-After 等待。
5xx — 请求处理失败，客户端应使用有限重试。

high 表示有肯定的来源标记；medium 表示来源分歧；low 表示可用来源未标记；unknown 表示没有有效信号。即使 HTTP 返回 200，单个数据源也可能超时、限流或不可用，应读取 providers[].status。