네이버 클라우드 플랫폼의 상품 사용 방법을 보다 상세하게 제공하고, 다양한 API의 활용을 돕기 위해 [설명서][API 참조서]를 구분하여 제공하고 있습니다.

Geolocation API 참조서 바로가기 >>
Geolocation 설명서 바로가기 >>

GeoLocation API 개요

GeoLocation API의 요청과 응답 형식을 설명합니다. 네이버 클라우드 플랫폼에서 제공하는 응용 프로그램 인터페이스(API)를 네이버 클라우드 플랫폼 API라고 합니다. 네이버 클라우드 플랫폼 API는 RESTful 형태로 제공되며 HTTP GET 메소드 호출을 통해서 이루어집니다.

공통설정

  • Geolocation API는 v1, v2 두가지 버전을 제공하고 있습니다.

  • {GEOLOCATION_API_URL} (v1)

    https://ncloud.apigw.ntruss.com/geolocation/v1
    
  • request header (v1)
Header Description
x-ncp-apigw-timestamp 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(millisecond)로 나타낸 것이다.
APIGW 서버와 시간차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
x-ncp-apigw-api-key API Gateway에서 발급받은 키
x-ncp-iam-access-key NCP에서 발급받은 API Key 또는 IAM에서 발급받은 AccessKey
x-ncp-apigw-signature-v1 위 예제의 Body를 AccessKey와 맵핑되는 SecretKey로 암호화한 서명
HMAC 암호화 알고리즘은 HmacSHA256 사용
  • {GEOLOCATION_API_URL} (v2)

    https://geolocation.apigw.ntruss.com/geolocation/v2
    
  • request header (v2)

Header Description
x-ncp-apigw-timestamp 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(millisecond)로 나타낸 것이다.
APIGW 서버와 시간차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주
x-ncp-iam-access-key NCP에서 발급받은 API Key 또는 IAM에서 발급받은 AccessKey
x-ncp-apigw-signature-v2 위 예제의 Body를 AccessKey와 맵핑되는 SecretKey로 암호화한 서명
HMAC 암호화 알고리즘은 HmacSHA256 사용

Fade Out API

  • 기존 구 버젼 Geolocation API는 Oauth인증을 사용합니다. 2019년 6월 30일까지만 이용이 가능하며 v2를 사용하시길 바랍니다.
AUTHPARAMS
  • 사용자 인증 관련 정보
  • oauth_consumer_key=C4kKlae2T0iLv0exX47Eiv
  • oauth_signature_method=HMAC-SHA1
  • oauth_version=1.0
  • oauth_timestamp=1494042435
  • oauth_nonce=983853020394837722989312
  • oauth_signature=ksjjeRkja4R93onltPeVXewQyXxtEZjk6

API 요청 URL 사용 예는 다음과 같습니다.

https://api.ncloud.com/geolocation/?action=getLocation&ip=202.131.30.11&enc=utf8&ext=t&responseFormatType=xml&oauth_consumer_key= C4kKlae2T0iLv0exX47Eiv&oauth_nonce=983853020394837722989312&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1494042435&oauth_version=1.0&oauth_signature= ksjjeRkja4R93onltPeVXewQyXxtEZjk6
API 요청 예시 구성
구분 설명
https://api.ncloud.com/geolocation/? API URL
action=getLocation 액션
ip=202.131.30.11 액션파라미터
enc=utf8 액션파라미터
ext=t 액션파라미터
responseFormatType=xml 응답포맷
oauth_consumer_key=C4kKlae2T0iLv0exX47Eiv AUTHPARAMS
oauth_nonce=983853020394837722989312 AUTHPARAMS
oauth_signature_method=HMAC-SHA1 AUTHPARAMS
oauth_timestamp=1494042435 AUTHPARAMS
oauth_version=1.0 AUTHPARAMS
oauth_signature=ksjjeRkja4R93onltPeVXewQyXxtEZjk6 AUTHPARAMS

API References


GeoLocation

geoLocation

  • API명

    위치정보 조회

  • action

    geoLocation

  • 요청 파라미터

    • ip
      • 필수
      • 지역 정보를 알고자 하는 사용자 IP.
    • enc
      • 인코딩 방식('utf8' (기본값) 또는 'euckr')
    • ext
      • 추가 정보 포함 여부 ('t' (포함) 또는 'f' (비포함, 기본값))
    • responseFormatType
      • 응답 포맷을 선택 ('xml' (기본값) 또는 'json')
  • Example

    • 요청

      {GEOLOCATION_API_URL}/geoLocation
      ?ip=202.131.30.11
      &enc=utf8
      &ext=t
      &responseFormatType=xml
      
    • 응답

정상 출력 결과 (ext =f의 결과)

예1)

JSON 형식 XML 형식

예2)

JSON 형식 XML 형식

정상 출력 결과 (ext=t의 결과)

예1)

JSON 형식 XML 형식

예2)

JSON 형식 XML 형식

비정상 출력 결과

JSON 형식 XML 형식

출력 결과 설명

항목 의미
returnCode 응답코드값 (다음의 응답코드값 표를 참조)
requestId 매 요청마다 유일하게 생성되는 ID
country 국가코드로서 https://en.wikipedia.org/wiki/ISO_3166 외에 EU(유럽), AP(아시아, 호주), A1(Anonymous Proxy), A2(Satellite provider), O1(Other Country)를 포함
code 한국의 경우에 행정자치부에서 정하는 행정동 코드를 나타냄
r1 도, 광역시, 주
r2 시, 군, 구
r3
lat 위도
long 경도
net 통신사 이름

응답코드값

코드값 설명 대응 방안
0 OK
131000 항목을 찾을 수 없음 지역정보를 찾을 수 없는 경우에 발생합니다. 다른 IP를 이용해서 조회하세요.
131001 잘못된 IP 주소 공인 IP가 아닌 경우거나 IP 주소 형식이 잘못된 경우에 발생합니다. 정상적인 IP 주소 형식은 IPv4 - 위키백과를 참고하세요.
131002 내부 에러 GeoLocation 서버의 오류로 발생합니다. 일시적이 아닌 경우에는 고객센터를 통해 문의하세요.
131003 Quota 한도에 달함 설정한 Quota 한도만큼 API가 사용되었습니다. 네이버 클라우드 플랫폼 콘솔 > Naver API > GeoLocation > Quota Setting 메뉴에서 Quota를 변경할 수 있습니다.
131004 상품 이용 신청 전임 네이버 클라우드 플랫폼 콘솔 > Naver API > GeoLocation > Subscription 메뉴에서 이용신청한 후에 사용하세요.

이 외의 코드값에 대해서는 네이버 클라우드 플랫폼 포털 > 설명서(구, 사용자 가이드) > API를 참조하세요.

API 사용 예제

[API 사용 예제 다운로드]

연관 정보 바로가기

아래 가이드에서 연관 정보를 확인할 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...