geoLocation

Prev Next

Available in Classic and VPC

Specify an IP address to retrieve geolocation information.

Request

The following describes the request format for the endpoint. The request format is as follows:

Method URI
GET /geoLocation

Request headers

For headers common to GeoLocation APIs, see GeoLocation request headers.

Request query parameters

The following describes the parameters.

Field Type Required Description
ip String Required IP of the user whose geolocation you want to know
ext String Optional Whether to include additional information
  • t | f (default)
    • t: include
    • f: not include
enc String Optional Encoding type of the response result
  • utf8 (default) | euckr
responseFormatType String Optional Format of the response result
  • xml (default) | json

Request example

The following is a sample request.

curl --location --request GET 'https://geolocation.apigw.ntruss.com/geolocation/v2/geoLocation
?ip=**.**.**.**
&ext=t
&enc=utf8
&responseFormatType=json'
--header 'x-ncp-apigw-timestamp: {Timestamp}'
--header 'x-ncp-iam-access-key: {Access Key}'
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'

Response

The following describes the response format.

Response body

The following describes the response body.

Field Type Required Description
requestId String Required API request ID
returnCode String Required Normal code is 0, and the others are error codes
country String Required Country code corresponding to the IP address
  • Compliant with ISO 3166 standards
  • It includes EU (Europe), AP (Asia, Australia), A1 (Anonymous Proxy), A2 (Satellite provider), and O1 (other countries)
code String Required Administrative region codes defined by the Ministry of the Interior and Safety of the Republic of Korea
r1 String Required Do, metropolitan city, state
r2 String Required Si, gun, gu
r3 String Optional Dong, myeon, eup
lat Number Optional Latitude
long Number Optional Longitude
net String Optional Network provider name

Response status codes

The following describes the response status codes. For response status codes common to NAVER Cloud Platform, see Ncloud API response status codes.

HTTP status code Code Message Description
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
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

Response example

The following is a sample response.

  • If domestic, ext=f, responseFormatType=xml
<?xml version="1.0" encoding="utf-8"?>
<getLocationResponse>
    <returnCode>0</returnCode>
    <requestId>c4e52003-****-****-****-66c93acfd0d2</requestId>
    <geoLocation>
        <country>KR</country>
        <code>41135*****</code>
        <r1>Gyeonggi-do</r1>
        <r2>Bundang-gu, Seongnam-si</r2>
    </geoLocation>
</getLocationResponse>
  • If domestic, ext=f, responseFormatType=json
{
    "returnCode": 0,
    "requestId": "c4e52003-****-****-****-66c93acfd0d2",
    "geoLocation": {
        "country": "KR",
        "code": "41135*****",
        "r1": "Gyeonggi-do",
        "r2": "Bundang-gu, Seongnam-si",
    }
}
  • If overseas, ext=f, responseFormatType=xml
<?xml version="1.0" encoding="utf-8"?>
<getLocationResponse>
    <returnCode>0</returnCode>
    <requestId>c4e52003-****-****-****-66c93acfd0d2</requestId>
    <geoLocation>
        <country>US</country>
        <code></code>
        <r1>California</r1>
        <r2>San Francisco</r2>
    </geoLocation>
</getLocationResponse>
  • If overseas, ext=f, responseFormatType=json
{
    "returnCode": 0,
    "requestId": "c4e52003-****-****-****-66c93acfd0d2",
    "geoLocation": {
        "country": "US",
        "code": "",
        "r1": "California",
        "r2": "San Francisco",
    }
}
  • If domestic, ext=t, responseFormatType=xml
<?xml version="1.0" encoding="utf-8"?>
<getLocationResponse>
    <returnCode>0</returnCode>
    <requestId>c4e52003-****-****-****-66c93acfd0d2</requestId>
    <geoLocation>
        <country>KR</country>
        <code>41135*****</code>
        <r1>Gyeonggi-do</r1>
        <r2>Bundang-gu, Seongnam-si</r2>
        <r3>Jeongja-dong</r3>
        <lat>**.268***</lat>
        <long>**.030***</long>
        <net>Korea Telecom</net>
    </geoLocation>
</getLocationResponse>
  • If domestic, ext=t, responseFormatType=json
{
    "returnCode": 0,
    "requestId": "c4e52003-****-****-****-66c93acfd0d2",
    "geoLocation": {
        "country": "KR",
        "code": "41135*****",
        "r1": "Gyeonggi-do",
        "r2": "Bundang-gu, Seongnam-si",
        "r3": "Jeongja-dong",
        "lat": **.268***,
        "long": **.030***,
        "net": "Korea Telecom"
    }
}
  • If overseas, ext=t, responseFormatType=xml
<?xml version="1.0" encoding="utf-8"?>
<getLocationResponse>
    <returnCode>0</returnCode>
    <requestId>c4e52003-****-****-****-66c93acfd0d2</requestId>    
    <geoLocation>
        <country>US</country>
        <code></code>
        <r1>California</r1>
        <r2>San Francisco</r2>
        <r3></r3>
        <lat>**.769***</lat>
        <long>-***.393***</long>
        <net>Fastly</net>
    </geoLocation>
</getLocationResponse>
  • If overseas, ext=t, responseFormatType=xml
{
    "returnCode": 0,
    "requestId": "c4e52003-****-****-****-66c93acfd0d2",
    "geoLocation": {
        "country": "US",
        "code": "",
        "r1": "California",
        "r2": "San Francisco",
        "r3": "",
        "lat": **.769***,
        "long": -***.393***,
        "net": "Fastly"
    }
}

Example

You can download the GeoLocation example file to test the GeoLocation API or use it as an example.