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
現在の1分間ウィンドウでレート制限を超えました。

例

リクエスト

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では履歴ウィンドウではなく、ユーザーごとに直近1件の位置情報のみを保存します—VPN/データセンターを考慮した抑制機能がまだないため、高速なVPNの切り替えやモバイルネットワークのIPの入れ替わりによる誤検知が発生することを想定しておいてください。結果は最終的な判定ではなく、生の信号として扱ってください。このエンドポイントは1回のリクエスト/レスポンスの範囲を超えてuserIdに紐づく位置情報を保存するため、これを利用するとWatch-IPはお客様に代わってそのデータの処理者となります—データ処理契約(DPA)をご覧ください。

関連ページ