geocode
  • PDF

geocode

  • PDF

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?

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.