네이버 클라우드 플랫폼의 상품 사용 방법을 보다 상세하게 제공하고, 다양한 API의 활용을 돕기 위해 [설명서]와 [API 참조서]를 구분하여 제공하고 있습니다.
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 사용 |
- x-ncp-apigw-signature 생성 예제는 Ncloud APIs > 공통가이드 AUTHPARAMS 생성하기 예제를 참조하세요.
Fade Out API
- 기존 구 버젼 Geolocation API는 Oauth인증을 사용합니다. 2019년 6월 30일까지만 이용이 가능하며 v2를 사용하시길 바랍니다.
AUTHPARAMS
- 사용자 인증 관련 정보
- oauth_consumer_key={your_key}
- oauth_signature_method=HMAC-SHA1
- oauth_version=1.0
- oauth_timestamp=1494042435
- oauth_nonce=983853020394837722989312
- oauth_signature={obtain_signature}
API 요청 URL 사용 예는 다음과 같습니다.
https://api.ncloud.com/geolocation/?action=getLocation&ip=x.x.x.x&enc=utf8&ext=t&responseFormatType=xml&oauth_consumer_key={your_key}oauth_nonce=983853020394837722989312&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1494042435&oauth_version=1.0&oauth_signature={obtain_signature}
API 요청 예시 구성
구분 | 설명 |
---|---|
https://api.ncloud.com/geolocation/? |
API URL |
action=getLocation | 액션 |
ip=x.x.x.x | 액션파라미터 |
enc=utf8 | 액션파라미터 |
ext=t | 액션파라미터 |
responseFormatType=xml | 응답포맷 |
oauth_consumer_key={your_key} | AUTHPARAMS |
oauth_nonce=983853020394837722989312 | AUTHPARAMS |
oauth_signature_method=HMAC-SHA1 | AUTHPARAMS |
oauth_timestamp=1494042435 | AUTHPARAMS |
oauth_version=1.0 | AUTHPARAMS |
oauth_signature={obtain_signature} | AUTHPARAMS |
API References
GeoLocation
geoLocation
API명
위치정보 조회
action
geoLocation
요청 파라미터
- ip
- 필수
- 지역 정보를 알고자 하는 사용자 IP.
- enc
- 인코딩 방식('utf8' (기본값) 또는 'euckr')
- ext
- 추가 정보 포함 여부 ('t' (포함) 또는 'f' (비포함, 기본값))
- responseFormatType
- 응답 포맷을 선택 ('xml' (기본값) 또는 'json')
- ip
Example
요청
{GEOLOCATION_API_URL}/geoLocation ?ip=x.x.x.x &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 사용 예제
연관 정보 바로가기
아래 가이드에서 연관 정보를 확인할 수 있습니다.