---
title: "Geocoding"
slug: "application-maps-geocoding"
updated: 2026-09-17T09:35:41Z
published: 2026-09-17T09:35:41Z
canonical: "api.ncloud-docs.com/application-maps-geocoding"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geocoding

Available in VPC

Search for address information associated with the address entered.

## Request

This section describes the request format. The method and URI are 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 information about the headers common to all Maps APIs, see [Maps request headers](/docs/en/application-maps-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### Request query parameters

You can use the following query parameters with your request:

| 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. - Example: `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 request example is as follows:

```
curl --location --request GET 'https://maps.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

This section describes the response format.

### Response body

The response body includes the following data:

| 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: [addresses](/docs/en/application-maps-geocoding#addresses) |
| `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: [addressElements](/docs/en/application-maps-geocoding#addressElements) |
| `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 information about the HTTP status codes common to all Maps APIs, see [Maps response status codes](/docs/en/application-maps-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### Response example

The response example is as follows:

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