• PDF


    • PDF

    Article summary


    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.


    curl -G "" \
        --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

    ParameterData typeRequiredDescription
    coordinatestringN- Search center coordinates
    - Input in lon and lat format
    filterstringN- 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)
    languagestringN- Add language=eng to enable English-based address search
    Default value: kor
    pagenumberN- Page number
    Default value: 1
    countnumberN- Number of results
    Input range: 1~100
    Default value: 10

    Request headers

    Header nameRequirement statusDescription
    X-NCP-APIGW-API-KEY-IDYClient ID issued when registering the app
    X-NCP-APIGW-API-KEYYClient secret issued when registering the app
    X-NCP-APIGW-API-KEY:{Client Secret}
    AcceptN- 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.


    Response bodies

    PropertyData typeRequiredDescription
    status                                  string      Y        Search result status code
    errorMessagestringNMessage when an exception occurs
    metaobjectNSearch metadata
    meta.totalCountnumberNTotal number of search results
    meta.pagenumberNCurrent page number
    meta.countnumberNNumber of results on page
    addressesarrayNList of address search results
    addresses[].roadAddressstringNRoad name address
    addresses[].jibunAddressstringNLot number address
    addresses[].englishAddressstringNAddress in English
    addresses[].xstringNx coordinate (longitude)
    addresses[].ystringNy coordinate (latitude)
    addresses[].distancedoubleNDistance from search center coordinates (Unit: meters)
    addresses[].addressElementsarrayNAddress elements


    Request examples

    curl -G "" \
        --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": [
                        "longName": "13561",
                        "shortName": "",
                        "code": ""
                "x": "127.10522081658463",
                "y": "37.35951219616309",
                "distance": 20.925857741585514
        "errorMessage": ""


    200OK-Normal response
    400INVALID_REQUESTBad Request ExceptionRequest error
    500SYSTEM_ERRORUnexpected ErrorError 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.