MENU
      Geocoding API

        Geocoding API


        Article summary

        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:

        MethodURI
        GET/geocode

        Request headers

        The following describes the request headers.

        FieldRequiredDescription
        AcceptRequiredResponse 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.

        FieldTypeRequiredDescription
        queryStringRequiredAddress to search
        coordinateStringOptionalSearch center coordinates (longitude, latitude)
        • Display search results in order of proximity to the entered coordinates
        filterIntegerOptionalSearch 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
        languageStringOptionalResponse result language
        • kor (default) | eng
          • kor: Korean
          • eng: English
        pageNumberOptionalPage number
        • 1 (default)
        countNumberOptionalResult 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'
        Shell

        Response

        The following describes the response format.

        Response body

        The following describes the response body.

        FieldTypeRequiredDescription
        statusString-Response code
        metaObject-Metadata
        meta.totalCountNumber-Number of response results
        meta.pageNumber-Current page number
        meta.countNumber-Number of results in page
        addressesArray-Address information list
        errorMessageString-Error message
        • Displayed only when a 500 error (unknown error) occurs

        addresses

        The following describes addresses.

        FieldTypeRequiredDescription
        roadAddressString-Road name address
        jibunAddressString-Land-lot number address
        englishAddressString-English address
        addressElementsArray-Address component information
        xString-X coordinate (longitude)
        yString-Y coordinate (latitude)
        distanceDouble-Distance from center coordinates (m)

        addressElements

        The following describes addressElements.

        FieldTypeRequiredDescription
        typeArray-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
        longNameString-Address component name
        shortNameString-Address component abbreviated name
        codeString--

        Response status codes

        The following describes the response status codes.

        HTTP status codeCodeMessageDescription
        200OK-Request processing successful. Normal response
        400INVALID_REQUEST-Request error
        500SYSTEM_ERRORUnexpected ErrorUnknown 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": ""
        }
        JSON

        Was this article helpful?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.