Watch-IP

IP 주소를 배치로 조회하기

IP 주소 목록을 하나의 엔드포인트로 전송하고 그에 대응하는 위치 결과 목록을 받으세요. Watch-IP의 대량 IP 조회 API는 백엔드 보강 워크플로를 위해 요청당 최대 100개의 IPv4 및 IPv6 주소를 받습니다. 시크릿 키는 서버에 두고, 입력 순서대로 응답을 처리하며, 원본 데이터와의 연결을 잃지 않으면서 누락된 레코드를 처리하세요.

조회 요금제 보기단일 IP 조회와 비교하기 →

한 번의 요청, 최대 100개 주소

ips 배열을 담은 JSON 객체로 POST /v1/lookup을 사용하세요. 각 배치는 최소 1개, 최대 100개의 주소를 포함할 수 있으며, 같은 목록에 IPv4와 IPv6 주소를 혼합할 수 있습니다. 응답은 순서가 유지된 조회 결과를 results 배열로 감싸며, 각 결과는 found와 null이 될 수 있는 위치 필드를 포함한 단일 IP 조회와 동일한 형태를 사용합니다.

결과를 원본 레코드와 정렬된 상태로 유지하기

성공한 배치에서는 각 입력 주소에 대해 하나의 결과가 같은 순서로 반환됩니다. 제출한 목록과 함께 자체 레코드 식별자를 유지해 결과를 원본 행에 다시 연결할 수 있도록 하세요. 레코드를 찾지 못하면 해당 행을 보존하고 위치를 이용 불가로 표시하며, 필드 하나만 누락된 경우에는 나머지 결과를 그대로 유지하세요. 누락된 좌표를 0으로 대체하지 마세요 — 데이터 부재를 잘못된 지도 위치로 바꾸게 됩니다.

제출 전에 검증하기

빈 목록, 100개를 초과하는 목록, 형식이 잘못된 IP는 요청 오류를 발생시킵니다 — 형식이 잘못된 주소 하나가 나머지 입력에 대한 부분 성공 결과를 만드는 대신 배치 전체를 거부합니다. 전송 전에 입력을 검증하고 긴 목록을 배치로 나누며, 재시도가 실수로 전체 작업을 반복하지 않도록 완료된 배치를 기록해 두세요.

배칭이 바꾸는 것 이해하기

배칭은 목록을 제출하는 데 필요한 HTTP 요청 수를 줄여줍니다. 데이터 소스를 바꾸지 않고, 보안 필드를 추가하지 않으며, 100건의 조회를 하나의 사용 단위로 만들지도 않습니다 — 조회 사용량은 승인된 요청에서 제출된 IP 단위로 기록되므로, 요금제 선택 시 총 조회량과 요청 속도를 모두 고려해야 합니다. 분당 속도 제한은 항목 수가 아니라 HTTP 호출 수를 셉니다. 최대 100개의 IP 또는 이메일 주소를 담은 배치는 1건의 요청으로 계산되며, 각 항목은 여전히 월간 요청 한도에 개별적으로 계산됩니다.

요청 및 응답 형태

ips
요청 본문: 1~100개의 IPv4 또는 IPv6 주소로 이루어진 JSON 배열입니다.
results
응답: 제출한 순서대로 입력 주소마다 하나의 항목을 가진 순서가 유지된 배열입니다.
results[].found, results[].country, ...
각 결과는 단일 IP 조회 응답과 동일한 형태와 null 허용 규칙을 사용합니다 — IP 조회 제품 페이지를 참고하세요.

배치 요청 보내기

cURL — POST /v1/lookup

curl --fail-with-body \
  'https://api.watch-ip.com/v1/lookup' \
  --header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"ips":["8.8.8.8","2001:4860:4860::8888"]}'

이 예시 주소들은 특정 현재 위치 값을 의미하지 않습니다. 먼저 서버 환경에서 WATCH_IP_SECRET_KEY를 설정하세요.

자주 묻는 질문

배치에는 몇 개의 IP 주소를 담을 수 있나요?

현재 최대치는 100개입니다. 긴 목록은 각각 1~100개의 주소를 포함하는 요청으로 나누세요.

배치에 IPv4와 IPv6를 함께 담을 수 있나요?

네. 모든 주소는 유효해야 하며, 데이터베이스 커버리지는 주소마다 다를 수 있습니다.

결과는 입력 순서대로 반환되나요?

네. 성공적으로 승인된 배치는 입력 주소마다 같은 순서로 하나의 결과를 반환합니다.

IP 하나의 형식이 잘못되면 어떻게 되나요?

요청 전체가 거부됩니다. 제출 전에 입력을 검증하세요 — 이 엔드포인트는 형식이 잘못된 입력에 대해 부분 성공을 제공하지 않습니다.

배치 하나는 조회 하나로 청구되나요?

아닙니다. 사용량은 IP 단위로 측정됩니다. 대규모 작업의 비용을 추정하기 전에 현재 조회 가격과 검증된 청구 예시를 확인하세요.

CSV 파일을 업로드할 수 있나요?

문서화된 엔드포인트는 주소의 JSON 배열을 받습니다. 애플리케이션에서 자체 CSV를 읽어 배치로 제출할 수 있으며, 호스팅된 CSV 업로드 인터페이스는 이 API에 포함되어 있지 않습니다.

대량 조회에도 VPN이나 Tor 확인이 포함되나요?

아닙니다. 현재 대량 응답은 서드파티 지오로케이션 데이터베이스의 위치 결과입니다. 방문자 지오의 보안 지표는 조회 응답에는 없는 별도의 기능입니다.

관련 페이지