In order to provide detailed descriptions of the various NAVER CLOUD PLATFORM services, and to facilitate use of various APIs, we offer [Manual] and [API reference] separately.
GeoLocation API overview
This document describes the request and response formats of GeoLocation API. NAVER CLOUD PLATFORM provides a set of application programming interfaces (APIs), which is called NAVER CLOUD PLATFORM APIs. NAVER CLOUD PLATFORM APIs are RESTful, using HTTP GET methods.
Common
Geolocation API provide v1 and v2.
{GEOLOCATION_API_URL} (v1)
https://ncloud.apigw.ntruss.com/geolocation/v1
request header (v1)
Header | Description |
---|---|
x-ncp-apigw-timestamp | It is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC. If the time difference with the APIGW server is more than 5 minutes, the request is considered invalid. |
x-ncp-apigw-api-key | API key issued by API Gateway |
x-ncp-iam-access-key | API key issued by NAVER CLOUD PLATFORM or access key issued by IAM |
x-ncp-apigw-signature-v1 | Signature used to encrypt the body of the example with the “secret key” that maps with the “access key.” The HMAC encryption algorithm is HMAC SHA256. |
{GEOLOCATION_API_URL} (v2)
https://geolocation.apigw.ntruss.com/geolocation/v2
request header (v2)
Header | Description |
---|---|
x-ncp-apigw-timestamp | It is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC. If the time difference with the APIGW server is more than 5 minutes, the request is considered invalid. |
x-ncp-iam-access-key | API key issued by NAVER CLOUD PLATFORM or access key issued by IAM |
x-ncp-apigw-signature-v2 | Signature used to encrypt the body of the example with the “secret key” that maps with the “access key.” The HMAC encryption algorithm is HMAC SHA256. |
- x-ncp-apigw-signature Ncloud APIs > Common Guide Please refer to "Create AUTHPARAMS".
Fade Out API
- Old version Geolocation API use Oauth. This API is supported util 2019. 6. 30. Recommed use v2 API.
AUTHPARAMS
- User Authentication related information
- oauth_consumer_key={your_key}
- oauth_signature_method=HMAC-SHA1
- oauth_version=1.0
- oauth_timestamp=1494042435
- oauth_nonce=983853020394837722989312
- oauth_signature={obtain_signature}
Here is an example of using an API request 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 Request Sample Components
Classification | Description |
---|---|
https://api.ncloud.com/geolocation/? |
API URL |
action=getLocation | Action |
ip=x.x.x.x.x | Action Parameter |
enc=utf8 | Action Parameter |
ext=t | Action Parameter |
responseFormatType=xml | Response Format |
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 name
Get geolocation
Action
geoLocation
Request parameters
- ip
- Required
- User’s IP address which you want to know geolocation of.
- enc
- Encoding method ('utf8' (default) or 'euckr')
- ext
- Indicates whether to contain extra information ('t' (include) or 'f' (not include, default))
- responseFormatType
- Select reponse format ('xml' (default) or 'json')
- ip
Example
Request
{GEOLOCATION_API_URL}/geoLocation ?ip=x.x.x.x &enc=utf8 &ext=t &responseFormatType=xml
Response
On success (ext =f)
Example 1)
JSON | XML |
---|---|
![]() |
![]() |
Example 2)
JSON | XML |
---|---|
![]() |
![]() |
On success (ext =t)
Example 1)
JSON | XML |
---|---|
![]() |
![]() |
Example 2)
JSON | XML |
---|---|
![]() |
![]() |
On failure
JSON | XML |
---|---|
![]() |
![]() |
Response description
Property | Description |
---|---|
returnCode | Response code (refer to the “Response code” table below.) |
requestId | Unique ID created for each request |
country | County code, including EU (Europe), AP (Asia, Australia), A1 (Anonymous Proxy), A2 (Satellite provider), O1 (Other Country) as well as https://en.wikipedia.org/wiki/ISO_3166. |
code | Administrative code defined by the Ministry of Government Administration and Home Affairs in Korea. |
r1 | Province, metropolitan city, state |
r2 | Si, Gun, Gu |
r3 | Dong |
lat | Latitude |
long | Longitude |
net | Network operator name |
Response code
Code | Description | Cause and countermeasure |
---|---|---|
0 | OK | |
131000 | Item not found. | This error occurs when geolocation information that matches the requested IP address is not found. Try again with another IP address. |
131001 | Invalid IP address | This error occurs when the requested IP address is not a public IP address or is invalid. For information on the valid IP address format, refer to "IPv4 - Wikipedia." |
131002 | Internal error | This error occurs due to internal errors of the GeoLocation server. If the problem persists, contact our Help Center. |
131003 | Quota limit reached. | This error occurs when the number of API calls reaches the defined quota limit. Go to NAVER CLOUD PLATFORM’s Console, and click GeoLocation > Quota Setting to change the quota. |
131004 | No subscription | Go to NAVER CLOUD PLATFORM’s Console, and click GeoLocation > Subscription to request the GeoLocation service. |
For other response codes, refer to Manual > API in NAVER CLOUD PLATFORM’s portal.
API Example
See also
You can see the related topic below.