Geocoding

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": ""
}