Geocoding API

English

Geocoding API

Article summary

Did you find this summary helpful?

Thank you for your feedback

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

Was this article helpful?

What's Next

Reverse Geocoding API

Table of contents

Request
Response