Watch-IP

将登录位置与此前存储的位置进行比较

在较短时间内，基于 IP 推断出的位置发生较大变化，可能值得审查。POST /v1/risk/check 会将用户当前的位置估算值与此前存储的位置点进行比较，并返回距离、经过时间、推算速度以及风险分类——在集成之前，请先联系我们确认可用性，因为独立的风险方案执行机制与结账就绪状态尚未得到验证。

沟通风险检测接入阅读风险检测参考文档 →

可用性

该端点与 IP 查询共用同一套私密密钥中间件，该中间件只检查密钥是否为私密密钥——并不会独立强制执行单独的风险方案系列，且预置的风险定价目前尚未配置有效价格。在生产环境中依赖该功能之前，请与我们确认当前的条款与可用性。

输入参数与私密密钥的使用

向 POST /v1/risk/check 发送包含 userId、ip 以及可选的 commit 布尔值（默认为 true）的 JSON 请求体，并通过 Authorization: Bearer YOUR_SECRET_KEY 携带私密密钥——仅限服务器到服务器调用，切勿从浏览器发起。

首次观测

某个用户的首次检查没有此前的位置可供比较：它会返回 risk: "low"、impossibleTravel: false，distance/speed/elapsed 相关数值均为 null，previousLocation 也为 null；如果 commit 不为 false，则会将本次观测存储为新的基线。

后续观测

之后的检查会将此前位置点与当前位置点之间的大圆距离，与经过的时间进行比较，从而得出推算速度。低于 500 公里/小时，结果为 "low"；在 500 至 900 公里/小时之间，结果为 "medium"（一次真实的远程航班的速度可能恰好落在这一边界附近）；超过 900 公里/小时，结果为 "high"，且 impossibleTravel: true。

commit 标志

commit 默认值为 true。若要进行一次推测性的预检查——例如在做出提升级别的身份验证决策之前——可将其设为 false，此时会读取已存储的基线而不会移动它，从而确保合法的检查不会破坏用户真实的位置历史记录。

位置缺失

如果 ip 无法被解析出经纬度，该端点会返回 422，而不是给出一个低置信度的猜测值。

数据保留与删除

v1 针对每一个（您的账户，userId）组合，只存储一个位置——即最近一次已提交的观测结果——目前没有自动过期机制，也没有可用的删除端点；该数据会一直保留，直到被下一次已提交的检查覆盖。由于该数据在单次请求/响应周期之外仍会保存与 userId 关联的位置信息，使用该端点即表示 Watch-IP 作为您的数据处理方处理这些数据——详见数据处理协议（Data Processing Addendum）。

误报

v1 目前没有针对 VPN 或数据中心的抑制机制，因此快速切换 VPN 或普通的移动网络 IP 变动，都可能产生偏高的结果。请将每一次分类结果都视为您自身审查流程中的原始信号，而不是最终判定。

响应字段

risk
low、medium 或 high，取决于上述推算速度阈值。
impossibleTravel
risk: "high" 的布尔简写形式。
distanceKm, impliedSpeedKmh, elapsedSeconds
此前观测与当前观测之间的距离和时间，以及由此推算出的速度。在用户的首次检查中为 null。
previousLocation
本次调用之前存储的基线所对应的 country、latitude、longitude 与 observedAt。在用户的首次检查中为 null。
currentLocation
根据本次调用中提供的 ip 解析出的 country、latitude 与 longitude。

先预检查，再提交

后端 cURL

# 在自行做出身份验证决策之前的推测性检查——不会移动基线。
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", "commit": false}'

# 在自行完成的密码/双因素验证成功之后，提交新的基线。
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"}'

commit 默认值为 true，因此上面的第二次调用会更新已存储的基线；第一次调用带有 commit: false，则不会。

常见问题

首次检查会发生什么？

它始终会返回 risk: "low"，且 previousLocation 为 null——此时尚无可用于比较当前位置的对象。

它会抑制 VPN 跳跃吗？

不会。v1 目前没有针对 VPN 或数据中心的抑制机制，因此仅仅是在两次登录之间切换网络或 VPN 出口，就可能单独导致 medium 或 high 的结果。

high 结果能证明账户已被攻破吗？

不能。它只是一个基于距离与时间的原始计算结果。请将其与您自己的身份验证证据结合使用，而不是将其当作独立的最终判定。

我能避免更新基线吗？

可以——传入 commit: false 即可。检查仍会正常运行并返回结果，但存储的位置不会被替换。

此前的位置会保留多久？

会无限期保留，直到该 userId 的下一次已提交检查将其覆盖——当前实现中没有自动过期机制，也没有删除端点。

相关页面