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

> ## 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.

# driving

## 개요

길찾기 API는 지도 앱 메인 화면에서 주요 지역까지의 소요 시간과 거리, 예상 유류비, 통행 요금 정보를 제공합니다. 그리고 경로상 분기점에서 안내가 필요한 경우 해당 지점에서의 [guide code](/docs/ai-naver-mapsdirections15-driving#GuideCode)를 제공합니다.

## 요청

```
curl "https://naveropenapi.apigw.gov-ntruss.com/map-direction-15/v1/driving?start={출발지}&goal={목적지}&option={탐색옵션}" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v
```

### 요청 파라미터

길찾기 API의 쿼리 스트링 파라미터에 공통으로 해당되는 내용입니다.

- 별도의 정보가 없으면 거리의 단위는 meter, 시간의 단위는 milisecond(1/1000초)를 사용합니다.
- 문자열 인코딩은 UTF-8을 사용합니다.

| 파라미터 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| start | [request position format](/docs/ai-naver-mapsdirections15-driving#RequestPositionFormat) | Y | 출발지 |
| goal | [multiple request position format](/docs/ai-naver-mapsdirections15-driving#MultipleRequestPositionFormat) | Y | - 목적지 하나 이상의 목적지 정보를 전달할 수 있으며, 복수 개의 목적지를 입력할 때는 `:`로 연결 입력한 목적지 정보 중 가장 적은 비용으로 도달할 수 있는 목적지로 경로가 생성됨 목적지의 최대 개수는 10개이며, 최초의 최적 목적지 좌표를 기준으로 직선거리 3km 이내의 좌표만 유효하게 판정 |
| waypoints | [multiple request position format list](/docs/ai-naver-mapsdirections15-driving#MultipleRequestPositionFormatlist) | N | - 경유지. 최대 15개를 입력할 수 있으며 서로 다른 경유지의 구분자로 \|(pipe char)를 사용 |
| option | [option code](/docs/ai-naver-mapsdirections15-driving#OptionCode) | N | - 탐색 옵션 옵션은 최대 3개까지 동시에 요청할 수 있으며, 여러 옵션은 ‘:'로 연결 기본값은 traoptimal |
| cartype | [cartype code](/docs/ai-naver-mapsdirections15-driving#CartypeCode) | N | - 톨게이트 요금 계산용 차종 정보 기본값은 1 차종을 바탕으로 차량의 중량 또는 크기를 판단하지는 않음 3, 4, 5종은 option에서 traavoidtoll이 적용되지 않았더라도 하이패스 전용 톨게이트를 회피해서 탐색 일반적인 승용차는 모두 1종 |
| fueltype | [fueltype code](/docs/ai-naver-mapsdirections15-driving#FueltypeCode) | N | 유류비 계산용 유종(기본값은 gasoline) |
| mileage | double | N | - 설정된 유류에 해당하는 연비 사용하는 차량의 연비를 사용자가 직접 입력하고자 할 때 사용하는 파라미터 기본값은 14 |
| lang | [lang string code](/docs/ai-naver-mapsdirections15-driving#LanguageCode) | N | 언어 종류 (기본값은 ko) |

#### Request Position Format

필수 항목(경도, 위도)과 옵션 항목(이름, 지점 ID)을 `,` 문자로 연결한 문자열입니다.

- 옵션 항목은 항목에 맞는 prefix가 필요합니다.
- 옵션 항목값은 `,`, `:` 또는 `|` 문자를 포함할 수 없습니다.
- 숫자가 아닌 문자는 URL 인코딩이 필요합니다.
- 옵션 항목 간의 순서는 상관 없습니다.

다음은 request position format의 사용 예입니다.

- 기본 예: `127.12345,37.12345`
- 이름 옵션 항목을 추가한 예: `127.12345,37.12345,name=출발지이름`

#### Multiple Request Position Format

[request position format](/docs/ai-naver-mapsdirections15-driving#RequestPositionFormat) 여러 개를 `:` 문자로 연결한 문자열입니다.

- `waypoints`의 각 항목은 독립적인 경유지이므로 name을 사용한 여러 개의 [request position format](/docs/ai-naver-mapsdirections15-driving#RequestPositionFormat)을 사용할 수 있습니다.
  - `waypoints` 예 1: `127.12345,37.12345:128.12345,38.12345`
  - `waypoints` 예 2: `127.12345,37.12345:128.12345,38.12345,name=장소이름1`
  - `waypoints` 예 3: `127.12345,37.12345,name=장소이름1:128.12345,38.12345,name=장소이름2`

#### Multiple Request Position Format list

[multiple request position format](/docs/ai-naver-mapsdirections15-driving#MultipleRequestPositionFormat) 여러 개를 `|` 문자로 연결한 리스트 문자열입니다. 경유지 파라미터인 `waypoints`가 이 형식을 사용합니다.

- 경유지가 두 개이고 각 경유지에 좌표가 두 개씩 있는 경우의 예: `127.12345,37.12345:127.23456,37.23456|128.12345,38.12345:128.23456,38.23456`

#### Cartype Code

톨게이트 요금 계산용 차종 정보를 나타내는 코드입니다.

| 코드 | 설명 |
| --- | --- |
| 1 | 1종(소형차) 2축 차량. 윤폭 279.4mm 이하 승용차, 소형승합차, 소형화물차 |
| 2 | 2종(중형차) 2축 차량. 윤폭 279.4mm 초과, 윤거 1,800mm 이하 중형승합차, 중형화물차 |
| 3 | 3종(대형차) 2축 차량. 윤폭 279.4mm 초과, 윤거 1,800mm 초과 대형승합차, 2축 대형화물차 |
| 4 | 4종(대형화물차) 3축 대형화물차 |
| 5 | 5종(특수화물차) 4축 이상 특수화물차 |
| 6 | 1종(경형자동차) 배기량 1000cc 미만으로 길이 3.6m, 너비 1.6m, 높이 2.0m 이하 |

#### Fueltype Code

유류비 계산용 유종을 나타내는 코드입니다.

| 스트링 코드 | 설명 |
| --- | --- |
| gasoline | 휘발유. 유류비 계산 시 사용 |
| highgradegasoline | 고급 휘발유. 유류비 계산 시 사용 |
| diesel | 경유. 유류비 계산 시 사용 |
| lpg | LPG. 유류비 계산 시 사용 |

#### Option Code

탐색 옵션을 나타내는 코드입니다.(모든 경로는 교통정보를 반영하므로 출발지, 목적지, 옵션이 같더라도 같은 경로가 보장되지 않습니다.)

| 스트링 코드 | 탐색 종류 |
| --- | --- |
| trafast | 실시간 빠른길 |
| tracomfort | 실시간 편한길 |
| traoptimal | 실시간 최적 |
| traavoidtoll | 무료 우선 |
| traavoidcaronly | 자동차 전용도로 회피 우선 |

#### Language Code

지원되는 언어 종류를 나타내는 코드입니다.

| 스트링 코드 | 설명 |
| --- | --- |
| ko | 한국어 |
| en | 영어 |
| ja | 일본어 |
| zh | 중국어 간체 |

### 요청 헤더

| 헤더 명 | 설명 |
| --- | --- |
| X-NCP-APIGW-API-KEY-ID | 앱 등록 시 발급받은 Client ID `X-NCP-APIGW-API-KEY-ID:{Client ID}` |
| X-NCP-APIGW-API-KEY | 앱 등록 시 발급 받은 Client Secret `X-NCP-APIGW-API-KEY:{Client Secret}` |

### 요청 바디

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

## 응답

### 응답 바디

하위 구조체는 Object로 표현하며, route 내 각 항목의 속성은 일반적인 key-value 쌍(`"key": "value"`)으로 표현합니다.

| 속성 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| code | [result code](/docs/ai-naver-mapsdirections15-driving#ResultCode) | Y | 응답 결과 코드 |
| messge | string | Y | 응답 결과 문자열 |
| currentDateTime | string | Y | 탐색 시점 시간 정보. ISO datetime format 사용 |
| route | **key**: [option code](/docs/ai-naver-mapsdirections15-driving#OptionCode) **value**: [route unit ent](/docs/ai-naver-mapsdirections15-driving#RouteUnitEnt) array | Y | 응답결과 |

#### Route Unit Ent

경로 안내를 위한 속성들의 대분류를 나타냅니다.

| 속성 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| summary | [summary](/docs/ai-naver-mapsdirections15-driving#Summary) | Y | 요약 정보 |
| path | [lng-lat position format](/docs/ai-naver-mapsdirections15-driving#lnglatPositionFormat) array | Y | - 경로를 구성하는 모든 좌표열 해당 좌표들에는 0번부터 시작되는 index가 있으며, 이 index는 경로 정보를 표현하기 위한 pointIndex라는 명칭으로 활용됨 |
| section | [section unit](/docs/ai-naver-mapsdirections15-driving#SectionUnit) | N | 해당 경로를 구성하는 주요 도로에 관한 정보열(모든 경로를 포함하는 정보는 아님) |
| guide | [guide unit for ent](/docs/ai-naver-mapsdirections15-driving#GuideUnitforEnt) array | N | 안내 정보열 |

#### Summary

탐색된 경로의 요약 정보를 나타냅니다.

| 속성 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| start | [response position format](/docs/ai-naver-mapsdirections15-driving#ResponsePositionFormat) | Y | 출발지 |
| goal | [response position format](/docs/ai-naver-mapsdirections15-driving#ResponsePositionFormat) | Y | 목적지 |
| waypoints | [response position format](/docs/ai-naver-mapsdirections15-driving#ResponsePositionFormat) array | N | 경유지(경유하는 순서대로 array에 기록) |
| distance | int | Y | 전체 경로 거리(meters) |
| duration | int | Y | 전체 경로 소요 시간(milisecond(1/1000초)) |
| bbox | lenth 2인 lng-lat position array | Y | 전체 경로 경계 영역(left bottom point와 right top point 두 개의 point array로 제공) |
| tollFare | int | Y | 통행 요금(톨게이트) |
| taxiFare | int | Y | 택시 요금(지자체별, 심야, 시경계, 복합, 콜비 감안) |
| fuelPrice | int | Y | 해당 시점의 전국 평균 유류비와 연비를 감안한 유류비 |

#### Section Unit

탐색된 경로 중 주요 도로의 정보를 나타냅니다. 도로명을 기준으로 주행 길이가 긴 경로의 정보입니다.

| 속성 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| pointIndex | int | Y | 경로를 구성하는 좌표의 인덱스 |
| pointCount | int | Y | 형상점 수 |
| distance | int | Y | 거리(meters) |
| name | string | Y | 도로명 |
| congestion | [congestion code](/docs/ai-naver-mapsdirections15-driving#Congestioncode) | N | 구간 혼잡도 |
| speed | int | N | 평균 속도 |

#### Guide Unit for Ent

회전 안내가 필요한 지점과 회전 안내까지의 거리 정보를 제공합니다.

| 속성 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| pointIndex | int | Y | 경로를 구성하는 좌표의 인덱스 |
| type | [guide code](/docs/ai-naver-mapsdirections15-driving#GuideCode) | Y | 안내 종류 |
| instructions | string | N | 안내 문구 |
| distance | int | Y | 이전 guide unit의 경로 구성 좌표 인덱스로부터 해당 guide unit의 경로 구성 좌표 인덱스까지의 거리(meters) |
| duration | int | Y | 이전 guide unit의 경로 구성 좌표 인덱스로부터 해당 guide unit의 경로 구성 좌표 인덱스까지의 소요 시간(milisecond(1/1000초)) |

#### Result Code

ResultCode가 0이 아니면 탐색 실패입니다.

| HttpStatusCode | ResultCode | ResultMessage | 설명 |
| --- | --- | --- | --- |
| 200 | 0 | - | 길찾기 성공 |
| 400 | 1 | - | 출발지와 도착지가 동일 |
| 400 | 2 | - | 출발지 또는 도착지가 도로 주변이 아닌 경우 |
| 400 | 3 | - | 자동차 길찾기 결과 제공 불가 |
| 400 | 4 | - | 경유지가 도로 주변이 아닌 경우 |
| 400 | 5 | - | 요청 경로가 매우 긴 경우(경유지를 포함한 직선거리의 합이 1500km이상인 경우) |

#### lng-lat Position Format

경도, 위도로 된 좌표 정보를 나타냅니다. Length 2인 1차원 배열로, 경도, 위도 순서로 제공합니다(lng, lat). 예: `[127.001122, 37.001122]`

#### Response Position Format

출발지, 도착지, 경유지의 좌표 정보를 제공합니다.

| 속성 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| location | [lng-lat position](/docs/ai-naver-mapsdirections15-driving#lnglatPositionFormat) | Y | 지점 |
| dir | [view direction code](/docs/ai-naver-mapsdirections15-driving#ViewDirectionCode) | N | 경로상에서 location 좌표를 바라보는 방향(경유지와 목적지에 대해서만 존재할 수 있음) |

#### View Direction Code

경로상의 도착지/경유지에서 실제 도착지/경유지로 지정한 지점의 방향을 나타냅니다. 경로상 진행 방향 중심으로 방향을 지정합니다.

| 코드 | 설명 |
| --- | --- |
| 0 | 전방 |
| 1 | 왼쪽 |
| 2 | 오른쪽 |

#### Guide Code

경로상 회전이 발생하거나 추가 안내가 필요한 지점에서 어떻게 진행할지 안내합니다.

| 코드 | 설명 |
| --- | --- |
| 1 | 직진 방향 |
| 2 | 좌회전 |
| 3 | 우회전 |
| 4 | 왼쪽 방향 |
| 5 | 오른쪽 방향 |
| 6 | U턴 |
| 8 | 비보호 좌회전 |
| 11 | 왼쪽 8시 방향 |
| 12 | 왼쪽 9시 방향 |
| 13 | 왼쪽 11시 방향 |
| 14 | 오른쪽 1시 방향 |
| 15 | 오른쪽 3시 방향 |
| 16 | 오른쪽 4시 방향 |
| 21 | 로터리에서 직진 방향 |
| 22 | 로터리에서 U턴 |
| 23 | 로터리에서 왼쪽 7시 방향 |
| 24 | 로터리에서 왼쪽 8시 방향 |
| 25 | 로터리에서 왼쪽 9시 방향 |
| 26 | 로터리에서 왼쪽 10시 방향 |
| 27 | 로터리에서 왼쪽 11시 방향 |
| 28 | 로터리에서 12시 방향 |
| 29 | 로터리에서 오른쪽 1시 방향 |
| 30 | 로터리에서 오른쪽 2시 방향 |
| 31 | 로터리에서 오른쪽 3시 방향 |
| 32 | 로터리에서 오른쪽 4시 방향 |
| 33 | 로터리에서 오른쪽 5시 방향 |
| 34 | 로터리에서 6시 방향 |
| 41 | 왼쪽 도로로 진입 |
| 42 | 오른쪽 도로로 진입 |
| 47 | 휴게소로 진입 |
| 48 | 페리항로 진입 |
| 49 | 페리항로 진출 |
| 50 | 전방에 고속도로 진입 |
| 51 | 전방에 고속도로 진출 |
| 54 | 전방에 분기도로 진입 |
| 55 | 전방에 고가차로 진입 |
| 56 | 전방에 지하차도 진입 |
| 57 | 왼쪽에 고속도로 진입 |
| 58 | 왼쪽에 고속도로 진출 |
| 62 | 왼쪽에 고가차도 진입 |
| 63 | 왼쪽에 고가차도 옆길 |
| 64 | 왼쪽에 지하차도 진입 |
| 65 | 왼쪽에 지하차도 옆길 |
| 66 | 오른쪽에 고속도로 진입 |
| 67 | 오른쪽에 고속도로 진출 |
| 71 | 오른쪽에 고가차로 진입 |
| 72 | 오른쪽에 고가차도 옆길 |
| 73 | 오른쪽에 지하차도 진입 |
| 74 | 오른쪽에 지하차도 옆길 |
| 81 | 왼쪽에 본선으로 합류 |
| 82 | 오른쪽에 본선으로 합류 |
| 87 | 경유지 |
| 88 | 도착지 |
| 91 | 회전교차로에서 직진 방향 |
| 92 | 회전교차로에서 U턴 |
| 93 | 회전교차로에서 왼쪽 7시 방향 |
| 94 | 회전교차로에서 왼쪽 8시 방향 |
| 95 | 회전교차로에서 왼쪽 9시 방향 |
| 96 | 회전교차로에서 왼쪽 10시 방향 |
| 97 | 회전교차로에서 왼쪽 11시 방향 |
| 98 | 회전교차로에서 12시 방향 |
| 99 | 회전교차로에서 오른쪽 1시 방향 |
| 100 | 회전교차로에서 오른쪽 2시 방향 |
| 101 | 회전교차로에서 오른쪽 3시 방향 |
| 102 | 회전교차로에서 오른쪽 4시 방향 |
| 103 | 회전교차로에서 오른쪽 5시 방향 |
| 104 | 회전교차로에서 6시 방향 |
| 121 | 톨게이트 |
| 122 | 하이패스전용 톨게이트 |
| 123 | 원톨링 톨게이트 |

#### Congestion code

도로의 종별 및 실제 통행 속도 정보를 이용해 추정한 혼잡도 분류 코드입니다.

| 코드 | 설명 |
| --- | --- |
| 0 | 값 없음 |
| 1 | 원활 |
| 2 | 서행 |
| 3 | 혼잡 |

다음은 혼잡도를 기준으로 도로 종별 통행 속도를 나타낸 표입니다.

| (km/h) | 일반도로 | 국도 | 도시고속 | 고속도로 |
| --- | --- | --- | --- | --- |
| 원활 | 30 이상 | 40 이상 | 60 이상 | 70 이상 |
| 서행 | 15~30 | 20~40 | 30~60 | 40~70 |
| 혼잡 | 15 미만 | 20 미만 | 30 미만 | 40 미만 |

## 예시

### 요청 예시

```
curl "https://naveropenapi.apigw.gov-ntruss.com/map-direction-15/v1/driving?start=127.1058342,37.359708&goal=129.075986,35.179470&option=trafast"\
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v
```

### 응답 예시

```
{
    "code": 0,
    "message": "길찾기를 성공하였습니다.",
    "currentDateTime": "2018-12-21T14:45:34",
    "route": {
        "trafast": [
            {
                "summary": {
                    "start": {
                        "location": [
                            127.1058342,
                            37.3597078
                        ]
                    },
                    "goal": {
                        "location": [
                            129.0759853,
                            35.1794697
                        ],
                        "dir": 2
                    },
                    "distance": 382403,
                    "duration": 15372873,
                    "bbox": [
                        [
                            127.0833901,
                            35.1793188
                        ],
                        [
                            129.0817364,
                            37.3599059
                        ]
                    ],
                    "tollFare": 24500,
                    "taxiFare": 319900,
                    "fuelPrice": 46027
                },
                "path": [
                    [
                        127.1059968,
                        37.3597093
                    ],

                    ....

                    [
                        129.0764276,
                        35.1795108
                    ],
                    [
                        129.0762855,
                        35.1793188
                    ]
                ],
                "section": [
                    {
                        "pointIndex": 654,
                        "pointCount": 358,
                        "distance": 22495,
                        "name": "죽양대로",
                        "congestion": 1,
                        "speed": 60
                    },
                    {
                        "pointIndex": 3059,
                        "pointCount": 565,
                        "distance": 59030,
                        "name": "낙동대로",
                        "congestion": 1,
                        "speed": 89
                    },
                    {
                        "pointIndex": 4708,
                        "pointCount": 433,
                        "distance": 23385,
                        "name": "새마을로",
                        "congestion": 1,
                        "speed": 66
                    }
                ],
                "guide": [
                    {
                        "pointIndex": 1,
                        "type": 3,
                        "instructions": "정자일로1사거리에서 '성남대로' 방면으로 우회전",
                        "distance": 21,
                        "duration": 4725
                    },
                    {
                        "pointIndex": 8,
                        "type": 3,
                        "instructions": "불정교사거리에서 '수원·용인, 미금역' 방면으로 우회전",
                        "distance": 186,
                        "duration": 42914
                    },

 					....

                    {
                        "pointIndex": 6824,
                        "type": 14,
                        "instructions": "연산교차로에서 '서면교차로, 시청·경찰청' 방면으로 오른쪽 1시 방향",
                        "distance": 910,
                        "duration": 125240
                    },
                    {
                        "pointIndex": 6842,
                        "type": 88,
                        "instructions": "목적지",
                        "distance": 895,
                        "duration": 111333
                    }
                ]
            }
        ]
    }
}
```