본문으로 건너뛰기

IPS (IP Geolocation) API

loplat IPS API 는 국내 IPv4 주소를 받아 그 IP 의 행정구역(시도·시군구·읍면동) 위치를 반환하는 IP 위치 조회 API 입니다.

시작하기​

  1. loplat API 콘솔에 로그인합니다.
  2. IPS 를 시작하고 API 키를 발급받습니다. 무료 체험 조건은 IPS 소개 페이지를 참고하세요.
  3. 발급받은 키를 X-API-Key 헤더에 넣어 아래 엔드포인트를 호출합니다.
주의

API 키는 발급 시 한 번만 표시됩니다. 서버 측에 안전하게 보관하고, 앱 소스나 공개 저장소에 넣지 마세요.

요청​

GET https://api.loplat.com/v1/ips/{ip}
X-API-Key: {발급받은 API 키}

경로 파라미터​

파라미터설명
ip조회할 IPv4 주소. 점으로 구분한 10진수 4개(0~255)만 허용합니다. 선행 0(010.1.1.1)이나 앞뒤 공백은 오류로 처리합니다.
  • 국내 IP 만 조회할 수 있습니다. 해외 IP 는 422 로 응답합니다.
  • 사설·예약 대역(10.0.0.0/8, 192.168.0.0/16, 루프백 등)은 위치 조회 대상이 아닙니다.
  • IPv6 는 아직 지원하지 않습니다.

헤더​

헤더필수설명
X-API-Key필수콘솔에서 발급받은 API 키
X-Request-Id선택요청 식별자(1~64자, 영문·숫자·-·_). 같은 IP 를 같은 값으로 24시간 안에 다시 요청하면 처음 결과를 그대로 돌려주며 사용량을 다시 차감하지 않습니다. 응답 본문의 request_id 로 돌려줍니다.

응답​

정상 (HTTP 200)​

확인된 수준까지의 행정구역을 반환합니다. 모든 IP 에서 읍면동까지 제공하지는 않으며, 확인되지 않은 수준은 null 입니다.

필드설명
ip조회한 IP
country국가 코드(KR)
sido시도(예: 서울, 경기). 원본 약칭 표기를 그대로 사용합니다.
sigungu시군구. 확인되지 않으면 null
eupmyeondong읍면동. 확인되지 않으면 null
coordinates좌표. 일반 조회는 정밀 좌표를 제공하지 않으며 현재 null 입니다. 값이 오면 kind: "region_representative"(지역 대표 좌표)이므로 정밀 위치로 쓰지 마세요.
request_id요청 식별자. X-Request-Id 를 보냈으면 그 값, 아니면 서버가 생성한 값(req_ 접두)
charged이번 호출로 사용량이 차감되었는지 여부
idempotent_replay같은 X-Request-Id 재요청으로 이전 결과를 다시 돌려준 응답인지 여부
{
  "ip": "203.0.113.10",
  "country": "KR",
  "sido": "서울",
  "sigungu": "중구",
  "eupmyeondong": null,
  "coordinates": null,
  "request_id": "req_01H...",
  "charged": true,
  "idempotent_replay": false
}

오류​

오류가 나면 HTTP 상태 코드와 함께 아래 형태의 JSON 을 반환합니다. 원인은 error.code 로 구분하세요.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API 키가 없거나 유효하지 않다",
    "request_id": "req_7f5f5a1a708749779bcd4916"
  }
}
HTTPerror.code의미
400INVALID_IP_INPUTIP 형식 오류(선행 0, 공백, 0~255 범위 밖 등)
400UNSUPPORTED_IP_VERSIONIPv6 등 IPv4 가 아닌 주소
400PRIVATE_OR_RESERVED_IP사설·예약·루프백 등 위치 조회 대상이 아닌 대역
400INVALID_REQUEST_IDX-Request-Id 형식 오류
401INVALID_API_KEYAPI 키가 없거나 폐기·형식 오류
403TRIAL_EXPIRED무료 체험 기간 만료. 콘솔에서 요금제를 선택하세요.
403NO_ACTIVE_PLAN이용 중인 체험·요금제가 없음
403PAYMENT_PENDING / PAYMENT_FAILED요금제 결제 확인 중 / 결제 실패
403SUBSCRIPTION_EXPIRED구독 만료
404LOCATION_NOT_FOUND국내 IP 이지만 행정구역 위치를 확인하지 못함(데이터 없음, 고정 IP 가 아님 등)
409IDEMPOTENCY_KEY_REUSED같은 X-Request-Id 로 다른 IP 를 요청함
409IDEMPOTENCY_IN_FLIGHT같은 X-Request-Id 의 이전 요청이 아직 처리 중. 잠시 후 다시 요청하세요.
422OVERSEAS_IP_UNSUPPORTED지원하지 않는 해외 IP
429RATE_LIMITED요청 속도 한도 초과. Retry-After 헤더의 시간(초) 뒤에 다시 요청하세요.
429QUOTA_EXHAUSTED체험·요금제 포함량 소진. 재시도하지 말고 콘솔에서 요금제를 변경하세요.
503SERVICE_UNAVAILABLE일시적인 서버 장애 또는 구독 갱신 확인 중
  • 일부 오류 본문에는 안내 문구 키(notice)가 함께 포함됩니다.
  • 429 는 error.code 로 구분하세요. RATE_LIMITED 에만 Retry-After 헤더가 붙고, QUOTA_EXHAUSTED 는 재시도해도 성공하지 않습니다.

사용량 차감​

  • 행정구역이 하나 이상 확인된 정상 응답(HTTP 200)만 사용량에서 차감합니다.
  • 오류 응답(400·401·403·404·409·422·429·5xx)은 차감하지 않습니다.
  • 같은 X-Request-Id 재요청으로 이전 결과를 돌려받으면(idempotent_replay: true) 다시 차감하지 않습니다.
  • 요금제와 무료 체험 조건은 IPS 소개 페이지를 참고하세요.

정밀 위치 조회​

일반 조회는 행정구역만 제공합니다. 읍면동까지 확인된 IP 의 위치 좌표·주소·오차 반경이 필요하면 정밀 위치 조회를 이용하세요.

  • 콘솔에 로그인해 IP 를 입력하면 정밀 위치 제공 가능 여부를 먼저 확인할 수 있습니다. 결제 전에는 위치 값을 보여주지 않습니다.
  • 제공 가능한 IP 만 건별로 구매하며, 월 구독 없이도 구매할 수 있습니다. 무료 체험에는 포함되지 않습니다.
  • 구매한 결과는 콘솔의 조회 이력에서 추가 과금 없이 다시 볼 수 있습니다.
  • 결과의 데이터 기준 시점은 데이터 적재 시각이며, 현재 접속자의 실시간 위치를 보장하지 않습니다.
  • 정밀 위치 조회는 API 키 호출이 아니라 콘솔 화면에서 이용합니다. 가격은 IPS 소개 페이지를 참고하세요.

예제​

cURL​

curl https://api.loplat.com/v1/ips/203.0.113.10 \
  -H "X-API-Key: $LOPLAT_API_KEY" \
  -H "X-Request-Id: order-20261113-0001"

Python​

import os
import requests

ip = "203.0.113.10"
response = requests.get(
    f"https://api.loplat.com/v1/ips/{ip}",
    headers={"X-API-Key": os.environ["LOPLAT_API_KEY"]},
    timeout=10,
)

if response.status_code == 200:
    body = response.json()
    print(body["sido"], body["sigungu"], body["eupmyeondong"])
else:
    error = response.json()["error"]
    print(response.status_code, error["code"], error["message"])
노트

예제의 203.0.113.10 은 문서용 예약 대역(RFC 5737) 주소입니다. 실제 호출에서는 조회할 국내 공인 IP 를 넣으세요.

문의​

기술 문의, 해외 IP 연동이나 대량 사용(Enterprise) 계약은 dev@loplat.com 으로 연락해 주세요.