IP 查询 API 参考

GET/v1/lookup/{ip}

使用第三方 IP 地理定位数据库,解析您提供的单个 IPv4 或 IPv6 地址——其数据来源与响应结构均不同于 GET /v1/geo。仅限服务器到服务器调用;请从您的后端调用它,切勿从浏览器调用。

身份验证

通过 Authorization: Bearer YOUR_SECRET_KEY 提供一个私密密钥。与 GET /v1/geo 所使用的公开可用密钥不同,该密钥必须留在您的服务器上——在此处使用公开可用密钥会返回 403。

响应字段

ip: 您提供的 IP 地址,原样返回。
country、city、continent: 来自来源数据库的近似位置,不可用时为 null。
region: 一个次级行政区划代码(例如 "TX"),而不是地区名称——与 GET /v1/geo 的 region 字段结构不同。
postalCode、timezone: 当前的来源数据库不会填充这两个字段——始终为 null。
latitude、longitude: 近似坐标,不可用时为 null。
found: 当该 IP 没有匹配记录,或底层数据库暂时不可用时为 false——该字段并不区分这两种情况。

错误

400: 所提供的 IP 不是有效的 IPv4 或 IPv6 地址。
401: API 密钥缺失或无效。
403: 使用了公开可用密钥而不是私密密钥。
429: 当前一分钟窗口内的速率限制已超出。

示例

请求

curl https://api.watch-ip.com/v1/lookup/203.0.113.1 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

响应

{
  "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 单独计费,与您访问者地理位置方案的请求量彼此独立——具体定价与可用性请参阅 IP 查询产品页面。单次调用需要查询多个 IP?请改用批量端点。本端点的位置数据由 DB-IP 提供(IP Geolocation by DB-IP, db-ip.com — CC BY 4.0)。

相关页面