geoLocation

Article summary

Did you find this summary helpful?

Thank you for your feedback

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 See IPv4 Wikipedia for more information about IP address formats
`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 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

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.

Was this article helpful?

What's Next

getQuota

Table of contents

Request
Response
Example