Geocoding

Prev Next

Available in VPC

Search for address information associated with the address entered.

Request

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

Method URI
GET /geocode

Request headers

The following describes the request headers.

Field Required Description
Accept Required Response data format
  • application/json

For headers common to all Maps APIs, see Common Maps headers.

Request query parameters

The following describes the request query parameters.

Field Type Required Description
query String Required Address to search
coordinate String Optional Search center coordinates (longitude, latitude)
  • Display search results in order of proximity to the entered coordinates
filter Integer Optional Search result filter
  • HCODE | BCODE
    • hCODE: administrative dong code
    • BCODE: statutory dong code
  • Enter in the Filter type@code1;code2;...... format
  • <e.g.> HCODE@4113554500;4113555000
language String Optional Response result language
  • kor (default) | eng
    • kor: Korean
    • eng: English
page Number Optional Page number
  • 1 (default)
count Number Optional Result list size
  • 1 - 100 (default: 10)

Request example

The following is a sample request.

curl --location --request GET 'https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode?query=6, Buljeong-ro, Bundang-gu'\
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}' \
--header 'Accept: application/json'

Response

The following describes the response format.

Response body

The following describes the response body.

Field Type Required Description
status String - Response code
meta Object - Metadata
meta.totalCount Number - Number of response results
meta.page Number - Current page number
meta.count Number - Number of results in page
addresses Array - Address information list
errorMessage String - Error message
  • Displayed only when a 500 error (unknown error) occurs

addresses

The following describes addresses.

Field Type Required Description
roadAddress String - Road name address
jibunAddress String - Land-lot number address
englishAddress String - English address
addressElements Array - Address component information
x String - X coordinate (longitude)
y String - Y coordinate (latitude)
distance Double - Distance from center coordinates (m)

addressElements

The following describes addressElements.

Field Type Required Description
type Array - Address component type
  • SIDO | SIGUGUN | DONGMYUN | RI | ROAD_NAME | BUILDING_NUMBER | BUILDING_NAME | LAND_NUMBER | POSTAL_CODE
    • SIDO: si/do
    • SIGUGUN: si/gu/gun
    • DONGMYUN: dong/myeon
    • RI: ri
    • ROAD_NAME: road name
    • BUILDING_NUMBER: building number
    • BUILDING_NAME: building name
    • LAND_NUMBER: land number
    • POSTAL_CODE: postal code
longName String - Address component name
shortName String - Address component abbreviated name
code String - -

Response status codes

The following describes the response status codes.

HTTP status code Code Message Description
200 OK - Request processing successful. Normal response
400 INVALID_REQUEST - Request error
500 SYSTEM_ERROR Unexpected Error Unknown error
Note

For response status codes common to all Maps APIs, see Common Maps response status codes.

Response example

The following is a sample example.

{
    "status": "OK",
    "meta": {
        "totalCount": 1,
        "page": 1,
        "count": 1
    },
    "addresses": [
        {
            "roadAddress": "NAVER Green Factory, 6 Buljeong-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
            "jibunAddress": "NAVER Green Factory, 178-1, Jeongja-dong, Bundang-gu, Seongnam-si, Gyeonggi-do",
            "englishAddress": "6, Buljeong-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea",
            "addressElements": [
                {
                    "types": [
                        "SIDO"
                    ],
                    "longName": "Gyeonggi-do",
                    "shortName": "Gyeonggi-do",
                    "code": ""
                },
                {
                    "types": [
                        "SIGUGUN"
                    ],
                    "longName": "Bundang-gu, Seongnam-si",
                    "shortName": "Bundang-gu, Seongnam-si",
                    "code": ""
                },
                {
                    "types": [
                        "DONGMYUN"
                    ],
                    "longName": "Jeongja-dong",
                    "shortName": "Jeongja-dong",
                    "code": ""
                },
                {
                    "types": [
                        "RI"
                    ],
                    "longName": "",
                    "shortName": "",
                    "code": ""
                },
                {
                    "types": [
                        "ROAD_NAME"
                    ],
                    "longName": "Buljeong-ro",
                    "shortName": "Buljeong-ro",
                    "code": ""
                },
                {
                    "types": [
                        "BUILDING_NUMBER"
                    ],
                    "longName": "6",
                    "shortName": "6",
                    "code": ""
                },
                {
                    "types": [
                        "BUILDING_NAME"
                    ],
                    "longName": "NAVER Green Factory",
                    "shortName": "NAVER Green Factory",
                    "code": ""
                },
                {
                    "types": [
                        "LAND_NUMBER"
                    ],
                    "longName": "178-1",
                    "shortName": "178-1",
                    "code": ""
                },
                {
                    "types": [
                        "POSTAL_CODE"
                    ],
                    "longName": "13561",
                    "shortName": "13561",
                    "code": ""
                }
            ],
            "x": "127.1054328",
            "y": "37.3595963",
            "distance": 0.0
        }
    ],
    "errorMessage": ""
}