Watch-IP

不可能旅行检测 API 参考

POST/v1/risk/check

将提供的 IP 解析出的位置,与存储的每用户基线位置进行比较,并对由此推算出的旅行速度进行分级。它是供您自己的风控流程使用的原始信号,而非最终结论——在集成之前请先联系我们确认可用性;独立的风险方案强制机制与结账就绪状态尚未得到验证。

身份验证

通过 Authorization: Bearer YOUR_SECRET_KEY 提供一个私密密钥,与查询端点使用的密钥类型相同。请发送包含 userId、ip 以及可选布尔值 commit(默认为 true;如需一次不应影响存储基线的试探性检测,请设为 false)的 JSON 请求体。

响应字段

risk
low、medium 或 high。
impossibleTravel
布尔值,表示前后两次位置之间推算出的速度是否超出合理的旅行速度。
distanceKm、impliedSpeedKmh、elapsedSeconds
前后两次观测之间的距离与时间,以及由此推算出的速度。当用户首次接受检测、没有可供比较的先前位置时为 null。
previousLocation
本次调用之前存储基线的 country、latitude、longitude 与 observedAt。当这是该 userId 的首次检测时为 null。
currentLocation
本次调用中所提供 ip 对应的 country、latitude 与 longitude。

错误

400
IP 地址格式错误或缺少 userId。
401
API 密钥缺失或无效。
403
使用了公开可用密钥而不是私密密钥。
422
所提供的 IP 无法解析出位置。
429
当前一分钟窗口内的速率限制已超出。

示例

请求

curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1"}'

响应

{
  "risk": "high",
  "impossibleTravel": true,
  "distanceKm": 8843.2,
  "impliedSpeedKmh": 4421.6,
  "elapsedSeconds": 7200,
  "previousLocation": { "country": "FR", "latitude": 48.8566, "longitude": 2.3522, "observedAt": "2026-09-06T12:00:00.000Z" },
  "currentLocation": { "country": "US", "latitude": 30.2672, "longitude": -97.7431 }
}

限制

v1 版本仅为每个用户存储最近一次的位置,而不是一个历史时间窗口——预计会因快速切换 VPN 或移动网络 IP 频繁变化而出现误报,因为目前尚无针对 VPN/数据中心的抑制机制。请将结果视为原始信号,而不是最终结论。由于该端点会将与 userId 关联的位置信息存储在单次请求/响应周期之外,使用该端点即意味着 Watch-IP 会代表您处理该数据——参见数据处理附录(DPA)。

相关页面