geocode

Overview

The address search API searches address information using lot numbers and street names as query words. Returns a list of addresses and details in JSON format.

Requests

curl -G "https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode" \
    --data-urlencode "query={address}" \
    --data-urlencode "coordinate={Search center coordinates}" \
    -H "X-NCP-APIGW-API-KEY-ID: {Client ID value issued upon application registration}" \
    -H "X-NCP-APIGW-API-KEY: {Client secret value issued upon application registration}" -v

Request parameters

Parameter	Data type	Required	Description
query	string	Y	Address
coordinate	string	N	- Search center coordinates - Input in lon and lat format
filter	string	N	- Search result filtering conditions - Input in the form of filterType@Code1;Code2;... Filter types provided are as follows: `HCODE`: Administrative dong code `BCODE`: Jurisdictional dong code (e.g., HCODE@4113554500;4113555000)
language	string	N	- Add language=eng to enable English-based address search Default value: kor
page	number	N	- Page number Default value: 1
count	number	N	- Number of results Input range: 1~100 Default value: 10

Request headers

Header name	Requirement status	Description
X-NCP-APIGW-API-KEY-ID	Y	Client ID issued when registering the app `X-NCP-APIGW-API-KEY-ID:{Client ID}`
X-NCP-APIGW-API-KEY	Y	Client secret issued when registering the app `X-NCP-APIGW-API-KEY:{Client Secret}`
Accept	N	- Response format JSON (default) and XML supported Set the desired format as MIME type `Accept: application/json` `Accept: application/xml`

Request bodies

This API does not require a request body.

Responses

Response bodies

Property	Data type	Required	Description
status	string	Y	Search result status code
errorMessage	string	N	Message when an exception occurs
meta	object	N	Search metadata
meta.totalCount	number	N	Total number of search results
meta.page	number	N	Current page number
meta.count	number	N	Number of results on page
addresses	array	N	List of address search results
addresses[].roadAddress	string	N	Road name address
addresses[].jibunAddress	string	N	Lot number address
addresses[].englishAddress	string	N	Address in English
addresses[].x	string	N	x coordinate (longitude)
addresses[].y	string	N	y coordinate (latitude)
addresses[].distance	double	N	Distance from search center coordinates (Unit: meters)
addresses[].addressElements	array	N	Address elements

Examples

Request examples

curl -G "https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode" \
    --data-urlencode "query=6, Buljeong-ro, Bundang-gu" \
    --data-urlencode "coordinate=127.1054328,37.3595963" \
    -H "X-NCP-APIGW-API-KEY-ID: {Client ID value issued upon application registration}" \
    -H "X-NCP-APIGW-API-KEY: {Client secret value issued upon application registration}" -v

Response examples

{
    "status": "OK",
    "meta": {
        "totalCount": 1,
        "page": 1,
        "count": 1
    },
    "addresses": [
        {
            "roadAddress": "Green Factory, 6, Buljeong-ro, Bundang-gu, Seongnam-si, Gyeonggi-do",
            "jibunAddress": "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": [
                        "POSTAL_CODE"
                    ],
                    "longName": "13561",
                    "shortName": "",
                    "code": ""
                }
            ],
            "x": "127.10522081658463",
            "y": "37.35951219616309",
            "distance": 20.925857741585514
        }
    ],
    "errorMessage": ""
}

Errors

HttpStatusCode	ResultCode	ErrorMessage	Description
200	`OK`	-	Normal response
400	`INVALID_REQUEST`	Bad Request Exception	Request error
500	`SYSTEM_ERROR`	Unexpected Error	Error without exception handling

Was this article helpful?

What's Next

Reverse Geocoding Overview

Table of contents

Overview
Requests
Responses
Examples
Errors