Watch-IP

백엔드에서 IP 주소 조회하기

제공된 IP 주소를 이용 가능한 국가, 지역, 도시, 근사 좌표 데이터로 해석하세요. Watch-IP의 IP 조회 API는 IPv4와 IPv6 입력을 받아 서드파티 IP 지오로케이션 데이터베이스 기반의 JSON 결과를 반환합니다. 서버에서 시크릿 API 키를 사용하고, 명확한 일치, 누락된 레코드, null이 될 수 있는 위치 필드를 중심으로 애플리케이션을 구성하세요.

조회 요금제 보기조회 접근 권한 문의하기 →

확인하려는 주소 제공하기

애플리케이션에서 수집한 IP 주소로 GET /v1/lookup/{ip}를 호출하고, Authorization: Bearer와 시크릿 키로 인증하세요. 이 조회는 요청에 사용된 연결이 아니라 URL의 주소를 해석하므로, 이미 IP 주소를 보유한 백엔드 워크플로(보고 및 지역 보강 정보 포함)에 적합합니다. 전달된 헤더에 의존하기 전에 애플리케이션이 최종 사용자의 IP를 어떻게 확보하는지 확인하고, 직접 제어하는 프록시 경로만 신뢰하세요. 일반적인 웹사이트 방문자 통합에는 공개 가능 키와 지역 보강 정보를 제공하는 브라우저 지오로케이션 엔드포인트가 다른 경로를 제공합니다.

단일 주소에서 배치로 확장하기

워크플로에 여러 IP 주소가 있다면 배치 엔드포인트가 단일 요청으로 최대 100개를 받아 같은 순서로 결과를 반환합니다. 동일한 조회 결과 형태와 동일한 서버 사이드 시크릿 키 인증 모델을 사용합니다. 배칭은 요청을 보내는 방식만 바꿀 뿐입니다 — 조회 사용량은 여전히 IP 단위로 측정되므로, 하나의 배치가 하나의 조회 사용 단위는 아닙니다.

근사 데이터를 중심으로 구성하기

하나의 IP는 공유 게이트웨이, 호스팅 네트워크, VPN 출구, 모바일 통신사 연결을 나타낼 수 있습니다. 위치 레코드는 불완전하거나 데이터 제공업체마다 다를 수 있습니다. 조회는 제공한 주소에 대한 맥락 정보로 사용하고, 개인의 거주지나 신원에 대한 증거로 사용하지 마세요.

응답 필드

ip
이 결과와 연관된 입력 주소입니다.
found
일치하는 데이터베이스 레코드를 찾았는지 여부입니다. false는 데이터베이스를 이용할 수 없거나 로드되지 않았다는 뜻일 수도 있으며, 해당 주소에 위치 데이터가 전혀 없다는 것을 증명하지는 않습니다.
country, continent
이용 가능한 경우 국가 및 대륙 코드입니다.
region
현재 매핑에 따른 하위 지역 식별자이며, 항상 전체 지역 이름은 아닙니다.
city, latitude, longitude
소스 데이터베이스에서 이용 가능한 경우 근사 도시와 좌표입니다.
postalCode, timezone
현재 소스 데이터베이스에서는 채워지지 않으며 항상 null입니다.

서버 사이드 요청 만들기

cURL — GET /v1/lookup/{ip}

curl --fail-with-body \
  'https://api.watch-ip.com/v1/lookup/8.8.8.8' \
  --header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}"

먼저 서버 환경에서 WATCH_IP_SECRET_KEY를 설정하세요. 8.8.8.8은 형식상 유효한 예시 주소이며, 이 스니펫이 특정 국가, 도시, 응답을 보장하지는 않습니다.

자주 묻는 질문

이 API로 다른 사람의 IP 주소를 조회할 수 있나요?

이 엔드포인트는 제공된 IP 주소를 받아 이용 가능한 데이터베이스 위치 데이터를 반환할 뿐, 개인의 이름, 정확한 주소, 신원은 반환하지 않습니다. 처리할 권한이 있는 데이터만 사용하세요.

IPv6를 지원하나요?

이 엔드포인트는 IPv4와 IPv6 입력을 검증합니다. 유효한 주소라도 데이터베이스 레코드나 일부 위치 필드가 없을 수 있습니다.

조회에 시간대, ASN, VPN 탐지가 포함되나요?

아닙니다. 현재 조회 응답에는 ASN이나 보안 지표가 포함되지 않으며, 소스 데이터베이스는 시간대나 우편번호 필드를 채우지 않습니다. 연결하는 클라이언트 모델이 애플리케이션에 맞는다면 방문자 지오로케이션을 별도로 검토하세요.

브라우저 JavaScript에서 요청을 보낼 수 있나요?

아닙니다 — 조회용 시크릿 키를 브라우저 코드에 절대 노출하지 마세요. 조회 호출은 백엔드에서 수행하고, 직접적인 브라우저 지오로케이션에는 공개 가능 키를 사용하는 방문자 엔드포인트를 이용하세요.

무료 방문자 키에 포함되나요?

아닙니다. 조회는 별도의 시크릿 키와 요금제 그룹을 사용하며, 무료 방문자 요금제는 서버 사이드 조회 접근 권한을 부여하지 않습니다.

found: false는 무엇을 의미하나요?

조회에서 일치하는 레코드를 반환하지 못했다는 뜻입니다. 현재 구현에서는 데이터베이스를 이용할 수 없거나 로드되지 않았을 때도 발생할 수 있으므로, "위치 확인 불가"를 표시하고 이 결과를 잘못된 입력, 인증 실패, 속도 제한 오류와 구분해서 다루세요.

관련 페이지