API-Referenz zur Erkennung unmöglicher Reisen

POST/v1/risk/check

Vergleicht den aufgelösten Standort einer angegebenen IP mit einer gespeicherten Baseline pro Nutzer und klassifiziert die implizierte Reisegeschwindigkeit. Ein Rohsignal für Ihren eigenen Betrugsabwehr-Workflow, kein endgültiges Urteil — kontaktieren Sie uns, um die Verfügbarkeit vor der Integration zu bestätigen; die unabhängige Durchsetzung eines Risiko-Tarifs und die Checkout-Bereitschaft wurden nicht verifiziert.

Authentifizierung

Stellen Sie einen geheimen Schlüssel über Authorization: Bearer YOUR_SECRET_KEY bereit, denselben Schlüsseltyp wie bei den Lookup-Endpoints. Senden Sie einen JSON-Text mit userId, ip und einem optionalen booleschen commit (Standard true; auf false setzen für eine spekulative Prüfung, die die gespeicherte Baseline nicht verändern soll).

Antwortfelder

risk: low, medium oder high.
impossibleTravel: Boolesche Kurzform dafür, ob die implizierte Geschwindigkeit zwischen dem vorherigen und dem aktuellen Standort eine plausible Reisegeschwindigkeit überschreitet.
distanceKm, impliedSpeedKmh, elapsedSeconds: Die Distanz und die Zeit zwischen der vorherigen und der aktuellen Beobachtung sowie die daraus implizierte Geschwindigkeit. Null bei der allerersten Prüfung eines Nutzers, wenn es keinen vorherigen Standort zum Vergleich gibt.
previousLocation: country, latitude, longitude und observedAt für die vor diesem Aufruf gespeicherte Baseline. Null, wenn dies die allererste Prüfung für diese userId ist.
currentLocation: country, latitude und longitude für die bei diesem Aufruf angegebene ip.

Fehler

400: Fehlerhafte IP-Adresse oder fehlende userId.
401: Fehlender oder ungültiger API-Schlüssel.
403: Es wurde ein veröffentlichbarer statt eines geheimen Schlüssels verwendet.
422: Die angegebene IP konnte keinem Standort zugeordnet werden.
429: Ratenlimit für das aktuelle Ein-Minuten-Fenster überschritten.

Beispiel

Anfrage

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"}'

Antwort

{
  "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 }
}

Limits

v1 speichert nur den einen zuletzt bekannten Standort pro Nutzer, kein Verlaufsfenster — erwarten Sie Fehlalarme durch schnelles VPN-Umschalten oder Mobilfunk-IP-Wechsel, da es noch keine VPN-/Rechenzentrum-bewusste Unterdrückung gibt. Behandeln Sie das Ergebnis als Rohsignal, nicht als endgültiges Urteil. Da dieser Endpoint einen mit einer userId verknüpften Standort über einen einzelnen Anfrage-/Antwortzyklus hinaus speichert, macht seine Nutzung Watch-IP zu einem Auftragsverarbeiter dieser Daten in Ihrem Namen — siehe die Vereinbarung zur Auftragsverarbeitung (AVV).