---
title: "Geocoding"
slug: "application-maps-geocoding"
updated: 2026-09-17T09:57:26Z
published: 2026-09-17T09:57:26Z
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

VPC環境で利用できます。

入力した住所と関連する住所情報を検索します。

## リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

| メソッド | URI |
| --- | --- |
| GET | /geocode |

### リクエストヘッダ

リクエストヘッダの説明は次の通りです。

| フィールド | 必須の有無 | 説明 |
| --- | --- | --- |
| `Accept` | Required | レスポンスデータの形式 - `application/json` |

Maps APIで共通して使用されるヘッダの詳細は、[Mapsのリクエストヘッダ](/docs/ja/application-maps-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94) をご参照ください。

### リクエストクエリパラメータ

リクエストクエリパラメータの説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `query` | String | Required | 検索対象の住所 |
| `coordinate` | String | Optional | 検索対象の中心座標(経度,緯度) - 入力した座標に近い順に検索結果を表示 |
| `filter` | Integer | Optional | 検索結果フィルタ - `HCODE` \| `BCODE` - `hCODE`: 行政洞コード - `BCODE`: 法定洞コード - **フィルタのタイプ@コード1;コード2;......** 形式で入力 - <例> `HCODE@4113554500;4113555000` |
| `language` | String | Optional | レスポンス結果言語 - `kor`(デフォルト) \| `eng` - `kor`: 韓国語 - `eng`: 英語 |
| `page` | Number | Optional | ページ番号 - 1(デフォルト) |
| `count` | Number | Optional | 結果リストのサイズ - 1~100 (デフォルト: 10) |

### リクエスト例

リクエストのサンプルコードは次の通りです。

```
curl --location --request GET 'https://maps.apigw.ntruss.com/map-geocode/v2/geocode?query=盆唐区佛亭路6' \
--header 'x-ncp-apigw-api-key-id: {API Key ID}' \
--header 'x-ncp-apigw-api-key: {API Key}' \
--header 'Accept: application/json'
```

## レスポンス

レスポンス形式を説明します。

### レスポンスボディ

レスポンスボディの説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `status` | String | - | レスポンスコード |
| `meta` | Object | - | メタデータ |
| `meta.totalCount` | Number | - | レスポンス結果数 |
| `meta.page` | Number | - | 現在のページ番号 |
| `meta.count` | Number | - | ページ内の結果数 |
| `addresses` | Array | - | 住所情報リスト: [addresses](/docs/ja/application-maps-geocoding#addresses) |
| `errorMessage` | String | - | エラーメッセージ - 500エラー(不明なエラー)発生時にのみ表示 |

#### `addresses`

`addresses`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `roadAddress` | String | - | 道路名住所 |
| `jibunAddress` | String | - | 地番住所 |
| `englishAddress` | String | - | 住所の英語表記 |
| `addressElements` | Array | - | 住所の構成要素情報: [addressElements](/docs/ja/application-maps-geocoding#addressElements) |
| `x` | String | - | X座標(経度) |
| `y` | String | - | Y座標(緯度) |
| `distance` | Double | - | 中心座標からの距離(m) |

#### `addressElements`

`addressElements`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `type` | Array | - | 住所の構成要素のタイプ - `SIDO` \| `SIGUGUN` \| `DONGMYUN` \| `RI` \| `ROAD_NAME` \| `BUILDING_NUMBER` \| `BUILDING_NAME` \| `LAND_NUMBER` \| `POSTAL_CODE` - `SIDO`: 市/道 - `SIGUGUN`: 市/郡/区 - `DONGMYUN`: 洞/面 - `RI`: 里 - `ROAD_NAME`: 道路名 - `BUILDING_NUMBER`: 建物番号 - `BUILDING_NAME`: 建物名 - `LAND_NUMBER`: 番地 - `POSTAL_CODE`: 郵便番号 |
| `longName` | String | - | 住所の構成要素名 |
| `shortName` | String | - | 住所の構成要素の略称 |
| `code` | String | - | - |

### レスポンスステータスコード

レスポンスステータスコードの説明は次の通りです。

| HTTPステータスコード | コード | メッセージ | 説明 |
| --- | --- | --- | --- |
| 200 | OK | - | リクエスト処理成功。正常レスポンス |
| 400 | INVALID_REQUEST | - | リクエストエラー |
| 500 | SYSTEM_ERROR | Unexpected Error | 不明なエラー |

参考

Maps APIで共通して使用されるレスポンスステータスコードの詳細は、[Mapsのレスポンスステータスコード](/docs/ja/application-maps-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)をご参照ください。

### レスポンス例

レスポンスのサンプルコードは次の通りです。

```
{
    "status": "OK",
    "meta": {
        "totalCount": 1,
        "page": 1,
        "count": 1
    },
    "addresses": [
        {
            "roadAddress": "京畿道城南市盆唐区佛亭路6 NAVERグリーンファクトリー",
            "jibunAddress": "京畿道城南市盆唐区亭子洞178-1 NAVERグリーンファクトリー",
            "englishAddress": "6, Buljeong-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea",
            "addressElements": [
                {
                    "types": [
                        "SIDO"
                    ],
                    "longName": "京畿道",
                    "shortName": "京畿道",
                    "code": ""
                },
                {
                    "types": [
                        "SIGUGUN"
                    ],
                    "longName": "城南市盆唐区",
                    "shortName": "城南市盆唐区",
                    "code": ""
                },
                {
                    "types": [
                        "DONGMYUN"
                    ],
                    "longName": "亭子洞",
                    "shortName": "亭子洞",
                    "code": ""
                },
                {
                    "types": [
                        "RI"
                    ],
                    "longName": "",
                    "shortName": "",
                    "code": ""
                },
                {
                    "types": [
                        "ROAD_NAME"
                    ],
                    "longName": "佛亭路",
                    "shortName": "佛亭路",
                    "code": ""
                },
                {
                    "types": [
                        "BUILDING_NUMBER"
                    ],
                    "longName": "6",
                    "shortName": "6",
                    "code": ""
                },
                {
                    "types": [
                        "BUILDING_NAME"
                    ],
                    "longName": "NAVERグリーンファクトリー",
                    "shortName": "NAVERグリーンファクトリー",
                    "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": ""
}
```