geoLocation

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 information about the headers common to all GeoLocation APIs, see GeoLocation request headers.

Request query parameters

You can use the following query parameters with your request:

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
`returnCode`	String	-	Normal code is 0, and the others are error codes
`requestId`	String	-	API request ID
`country`	String	-	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	-	Administrative region codes defined by the Ministry of the Interior and Safety of the Republic of Korea
`r1`	String	-	Do, metropolitan city, state
`r2`	String	-	Si, gun, gu
`r3`	String	-	Dong, myeon, eup
`lat`	Number	-	Latitude
`long`	Number	-	Longitude
`net`	String	-	Network provider name

Response status codes

For information about the HTTP status codes common to all GeoLocation APIs, see GeoLocation response status codes.

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.