비정상 이동 탐지 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은 사용자당 이력 윈도우가 아니라 가장 최근 위치 하나만 저장합니다 — 아직 VPN/데이터센터를 인식한 억제 기능이 없으므로, 빠른 VPN 전환이나 모바일 네트워크의 IP 변경으로 인한 오탐을 예상해야 합니다. 결과는 최종 판정이 아니라 원시 신호로 취급하세요. 이 엔드포인트는 단일 요청/응답 주기를 넘어 userId와 연결된 위치를 저장하므로, 이를 사용하면 Watch-IP가 귀하를 대신해 해당 데이터의 처리자가 됩니다 — 데이터 처리 부속계약(DPA)을 참고하세요.