Watch-IP

방문자 지오로케이션 API 레퍼런스

GET/v1/geo

연결된 클라이언트의 이용 가능한 위치 및 보강 정보를 반환합니다. 방문자의 연결 정보를 확인하려면 방문자의 브라우저에서 호출하세요 — 애플리케이션 서버에서 요청하면 대신 서버 자신의 연결 정보가 반환됩니다.

인증

X-Api-Key 헤더로 오리진에 고정된 공개 가능 키를 전달하거나, 대안으로 key 쿼리 파라미터를 사용할 수 있습니다. 접근 통제는 키를 비밀로 유지하는 데서 오는 것이 아니라 — 이 키는 브라우저 소스에 노출되도록 설계되었습니다 — 키에 설정된 오리진 허용 목록에서 비롯되며, 요청의 Origin/Referer 헤더와 대조하여 확인됩니다.

응답 필드

ip
연결된 클라이언트의 IP 주소입니다.
country, region, regionCode, city, postalCode, continent
대략적인 위치입니다 — 기반 엣지 데이터가 위치를 확인하지 못하면 null이 될 수 있습니다.
latitude, longitude
확인된 위치의 대략적인 좌표이며, 기기나 GPS 위치가 아닙니다.
timezone
IANA 타임존 이름이며, 이용할 수 없으면 null입니다.
isEUCountry
불리언 값입니다 — 위치 기반 플래그일 뿐 법적 판단이 아닙니다.
asn, asOrganization
연결된 네트워크와 그 운영자입니다 — 기반 데이터에서 제공되는 경우에 한하며, 그렇지 않으면 null입니다.
currency, callingCode
확인된 country로부터 도출된 지역 정보이며, 없으면 null입니다.
locale, holidays, compliance, tax, ageVerification
선택적으로 도출되는 보강 정보 그룹으로, 각각 독립적으로 null이 될 수 있습니다. 이들 중 어느 것도 법적, 세무적, 신원 판단이 아닙니다.
hostname
?include=hostname으로 요청했을 때만 존재하며, 역방향 DNS 조회 결과입니다 — 실패하면 null입니다.
security
이를 포함하지 않는 요금제에서는 완전히 생략됩니다. 존재할 경우: isTor, isVpn, isDatacenter, isThreat, isSanctionedNetwork — 목록 기반 지표입니다. IPv6에 대한 Tor 탐지는 현재 구현되어 있지 않습니다 — false는 위험이 없다는 뜻이 아니라 이용 가능한 데이터에서 일치하는 항목이 없다는 뜻입니다.

오류

401
API 키가 없거나 유효하지 않습니다.
403
요청의 Origin/Referer가 키의 오리진 허용 목록에 없습니다. 이 응답에는 CORS 헤더가 설정되지 않으므로, JSON 본문과 무관하게 브라우저가 응답을 차단합니다.
429
현재 고정된 1분 윈도우의 속도 제한을 초과했습니다.

예시

요청

curl https://api.watch-ip.com/v1/geo \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY"

응답 — 예시이며, 필드는 요금제와 이용 가능한 데이터에 따라 달라집니다

{
  "ip": "203.0.113.1",
  "country": "US",
  "region": "Texas",
  "regionCode": "TX",
  "city": "Austin",
  "postalCode": "78701",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "continent": "NA",
  "timezone": "America/Chicago",
  "isEUCountry": false,
  "asn": 12345,
  "asOrganization": "Example ISP",
  "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" },
  "callingCode": "+1"
}

제한 사항

요금제의 월간 요청 한도와 분당 속도 제한이 적용됩니다 — 요금제 안내를 참고하세요. 성공한 호출은 각각 하나의 geo 사용 이벤트로 기록됩니다.

관련 페이지