GeoLocation overview

GeoLocation is the only service in Korea that provides location information based on user IP addresses. This service enables location-based content personalization, ad targeting, traffic analysis, DRM management, and abuse/fraud detection. GeoLocation is an API service provided by NAVER Cloud Platform that searches the GeoLocation database for information on the region associated with an IP address queried by a customer’s server and returns that information to the customer’s server. The information provided includes the country, city/county/district, neighborhood, coordinates of nearby areas, and carrier information. Location data for each IP address is updated frequently throughout the day to ensure it always reflects the latest information. The NAVER Cloud Platform API is provided in a RESTful format and is accessed via HTTP GET method calls.

Common GeoLocation settings

Request

The following describes the common request format.

API URL

The request API URL is as follows:

https://geolocation.apigw.ntruss.com

Request headers

The following describes the request headers.

Field	Required	Description
`x-ncp-apigw-timestamp`	Required	This is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC. Request is considered invalid if the timestamp differs from the current time by more than 5 minutes. Unix timestamp format.
`x-ncp-iam-access-key`	Required	Access key issued on NAVER Cloud Platform Issue and check access key: See Create authentication key. Issue and check access key for sub account: See Create sub account.
`x-ncp-apigw-signature-v2`	Required	Base64-encoded signature that encrypts the request information with a secret key that maps to the access key issued on NAVER Cloud Platform, using the HMAC encryption algorithm (HmacSHA256). Issue and check secret key: See Create authentication key. Create signature: See Create signature.
`Content-Type`	Required	Request data format `application/json`

Response

The following describes the common response format.

Response body

The response body includes the following data:

error

error defines the API call failure information. The following describes error.

Field	Type	Required	Description
`error`	Object	-	Error code and message
`error.errorCode`	String	Required	Error code
`error.message`	String	Required	Error message
`error.details`	String	Required	Error message description

Response status codes

The following describes the response status codes.

HTTP status code	Code	Message	Description
204	-	OK (No Content)	Request succeeded
400	131000	No Entry	Unable to find geolocation information for the requested IP address Solution: Query using another IP
400	131001	Invalid IP	Non-public IP or invalid IP address format Solution: Enter the correct IP address by referring to IPv4 Wikipedia.
400	131002	Internal Server Error	GeoLocation server error Solution: Try again after a while, or contact Support if the issue persists.
400	131003	Quota Limit Reached	Exceeded the API call limit set by the user. Solution: Change the limit by increasing the quota in the Services > Application Services > GeoLocation > Quota Setting menu of the NAVER Cloud Platform console.
400	131004	Subscription Required	GeoLocation service subscription required Solution: Subscribe to the GeoLocation service from the Services > Application Services > GeoLocation > Subscription menu of the NAVER Cloud Platform console.
404	-	Not Found	Resource not found
500	-	Internal Server Error	Internal server error

Note

For information about the HTTP status codes common to NAVER Cloud Platform, see Ncloud API response status codes.

Response example

For response examples when a call is successful, see each API specification. The following is a sample response upon a failed call.

{
    "error": {
        "errorCode": 130001,
        "message": "Invalid Quota",
        "details": null
    }
}