Watch-IP

批量 IP 查询 API 参考

POST/v1/lookup

GET /v1/lookup/{ip} 的批量版本——在单次后端请求中最多解析 100 个 IPv4/IPv6 地址,并按提交时的相同顺序返回。

身份验证

通过 Authorization: Bearer YOUR_SECRET_KEY 提供一个私密密钥,与单个 IP 查询端点使用的密钥类型相同。

请求体

ips
一个包含 1 至 100 个 IPv4/IPv6 地址字符串的数组。整个批次会在开始任何查询之前完成校验——一个格式错误的地址会导致整个调用失败。

错误

400
ips 数组为空、超过 100 个 IP,或数组中存在格式错误的 IP。
401
API 密钥缺失或无效。
403
使用了公开可用密钥而不是私密密钥。
429
当前一分钟窗口内的速率限制已超出。

示例

请求

curl https://api.watch-ip.com/v1/lookup \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["203.0.113.1", "2001:db8::1"]}'

响应

{
  "results": [
    { "ip": "203.0.113.1", "country": "US", "region": "TX", "city": "Austin", "postalCode": null, "latitude": 30.2672, "longitude": -97.7431, "continent": "NA", "timezone": null, "found": true },
    { "ip": "2001:db8::1", "country": null, "region": null, "city": null, "postalCode": null, "latitude": null, "longitude": null, "continent": null, "timezone": null, "found": false }
  ]
}

限制

批次中的每个 IP 都会被单独计费与记录——一次包含 100 个 IP 的调用会记录 100 次查询用量事件,而不是 1 次。同一个 IP 提交两次会被计费两次。对于每分钟速率限制，整个调用只算一次请求。本端点的位置数据由 DB-IP 提供(IP Geolocation by DB-IP, db-ip.com — CC BY 4.0)。

相关页面