---
title: "geocode"
slug: "ai-naver-mapsgeocoding-geocode"
tags: ["Geocoding", "Maps"]
updated: 2026-10-22T10:46:41Z
published: 2026-10-22T10:46:41Z
canonical: "api-gov.ncloud-docs.com/ai-naver-mapsgeocoding-geocode"
---

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

# geocode

## 개요

주소 검색 API는 지번, 도로명를 질의어로 사용해서 주소 정보를 검색합니다. 검색 결과로 주소 목록과 세부 정보를 JSON 형태로 반환합니다.

## 요청

```
curl "https://naveropenapi.apigw.gov-ntruss.com/map-geocode/v2/geocode?query={주소}&coordinate=#{검색_중심_좌표}" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v
```

### 요청 파라미터

| 파라미터 | 데이터 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| query | string | Y | 주소 |
| coordinate | string | N | 검색 중심 좌표 ('lon,lat' 형식으로 입력) |
| filter | string | N | - 검색 결과 필터링 조건 '필터 타입@코드1;코드2;... ' 형식으로 입력 제공하는 필터 타입: `HCODE`: 행정동 코드 `BCODE`: 법정동 코드 예) HCODE@4113554500;4113555000 |
| language | string | N | - language=eng 추가 시 영문 주소 검색 활성화 기본값: kor |
| page | number | N | 페이지 번호 기본값: 1 |
| count | number | N | - 결과 목록 크기 입력 범위: 1~100 기본값: 10 |

### 요청 헤더

| 헤더 명 | 필수 여부 | 설명 |
| --- | --- | --- |
| X-NCP-APIGW-API-KEY-ID | Y | 앱 등록 시 발급받은 Client ID `X-NCP-APIGW-API-KEY-ID:{Client ID}` |
| X-NCP-APIGW-API-KEY | Y | 앱 등록 시 발급 받은 Client Secret `X-NCP-APIGW-API-KEY:{Client Secret}` |
| Accept | N | - 응답 포맷 JSON(기본값), XML 지원 MIME 타입으로 원하는 포맷 설정 `Accept: application/json` `Accept: application/xml` |

### 요청 바디

- 해당 API 는 요청 바디를 필요로 하지 않습니다.

## 응답

### 응답 바디

| 속성 | 데이터 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| status | string | Y | 검색 결과 상태 코드 |
| errorMessage | string | N | 예외 발생 시 메시지 |
| meta | object | N | 검색 메타 데이터 |
| meta.totalCount | number | N | 총 검색 건수 |
| meta.page | number | N | 현재 페이지 번호 |
| meta.count | number | N | 페이지 내 결과 개수 |
| addresses | array | N | 주소 검색 결과 목록 |
| addresses[].roadAddress | string | N | 도로명 주소 |
| addresses[].jibunAddress | string | N | 지번 주소 |
| addresses[].englishAddress | string | N | 영어 주소 |
| addresses[].x | string | N | x 좌표(경도) |
| addresses[].y | string | N | y 좌표(위도) |
| addresses[].distance | double | N | 검색 중심 좌표로부터의 거리(단위: 미터) |
| addresses[].addressElements | array | N | 주소를 이루는 요소들 |

## 예시

### 요청 예시

```
curl "https://naveropenapi.apigw.gov-ntruss.com/map-geocode/v2/geocode?query=분당구 불정로 6&coordinate=127.1054328,37.3595963" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v
```

### 응답 예시

```
{
    "status": "OK",
    "meta": {
        "totalCount": 1,
        "page": 1,
        "count": 1
    },
    "addresses": [
        {
            "roadAddress": "경기도 성남시 분당구 불정로 6 그린팩토리",
            "jibunAddress": "경기도 성남시 분당구 정자동 178-1 그린팩토리",
            "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": ""
}
```

## 에러 코드

| HttpStatusCode | ResultCode | ErrorMessage | Description |
| --- | --- | --- | --- |
| 200 | `OK` | - | 정상 응답 |
| 400 | `INVALID_REQUEST` | Bad Request Exception | 요청 에러 |
| 500 | `SYSTEM_ERROR` | Unexpected Error | 예외처리가 안된 에러 |