driving

개요

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

요청

curl "https://naveropenapi.apigw.ntruss.com/map-direction/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 Y 출발지.
goal multiple request position format Y 목적지. 하나 이상의 목적지 정보를 전달할 수 있으며, 복수 개의 목적지를 입력할 때는 :로 연결합니다. 입력한 목적지 정보 중 가장 적은 비용으로 도달할 수 있는 목적지로 경로가 생성됩니다.
목적지의 최대 개수는 10개이며, 최초의 최적 목적지 좌표를 기준으로 직선거리 3km 이내의 좌표만 유효하게 판정합니다.
waypoints multiple request position format list N 경유지.
최대 5개를 입력할 수 있으며 서로 다른 경유지의 구분자로 |(pipe char)를 사용합니다.
option option code N 탐색 옵션. 옵션은 최대 3개까지 동시에 요청할 수 있으며, 여러 옵션은 ‘:‘로 연결합니다. 기본값은 traoptimal입니다.
cartype cartype code N 톨게이트 요금 계산용 차종 정보. 기본값은 1입니다.
차종을 바탕으로 차량의 중량 또는 크기를 판단하지는 않습니다.
3, 4, 5종은 option에서 traavoidtoll이 적용되지 않았더라도 하이패스 전용 톨게이트를 회피해서 탐색합니다.
일반적인 승용차는 모두 1종입니다.
fueltype fueltype code N 유류비 계산용 유종. 기본값은 gasoline입니다.
mileage double N 설정된 유류에 해당하는 연비. 사용하는 차량의 연비를 사용자가 직접 입력하고자 할 때 사용하는 파라미터입니다. 기본값은 14입니다.
lang lang string code N 언어 종류. 기본값은 ko입니다.

Request Position Format

  • 필수 항목(경도, 위도)과 옵션 항목(이름, 지점 ID)을 , 문자로 연결한 문자열입니다.
  • 옵션 항목은 항목에 맞는 prefix가 필요합니다.
  • 옵션 항목값은 ,, : 또는 | 문자를 포함할 수 없습니다.
  • 숫자가 아닌 문자는 URL 인코딩이 필요합니다.
  • 옵션 항목 간의 순서는 상관 없습니다.
  • 지점id 옵션항목의 prefix: sessionid=
  • goal param 에서 지점id 가 사용되면 이로부터 추출된 입구점들이 모두 최적목적지 후보가 됩니다.
  • sessionid는 search place api를 통해 얻을 수 있습니다.

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

  • 기본 예: 127.12345,37.12345
  • 이름 옵션 항목을 추가한 예: 127.12345,37.12345,name=출발지이름
  • 지점id 옵션항목 추가: 127.12345,37.12345,sessionid=11223344
  • 이름, 지점id 옵션항목 추가: 127.12345,37.12345,sessionid=11223344,name=출발지이름

Multiple Request Position Format

request position format 여러 개를 : 문자로 연결한 문자열입니다.

  • waypoints의 각 항목은 독립적인 경유지이므로 name을 사용한 여러 개의 request position format을 사용할 수 있습니다.
    • waypoints 예 1: 127.12345,37.12345:128.12345,38.12345
    • waypoints 예 2: 127.12345,37.12345:128.12345,38.12345,sessionid=11223344,name=장소이름1
    • waypoints 예 3: 127.12345,37.12345,name=장소이름1:128.12345,38.12345,sessionid=11223344

Multiple Request Position Format list

multiple request position format 여러 개를 | 문자로 연결한 리스트 문자열입니다. 경유지 파라미터인 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 Y 응답 결과 코드
messge string Y 응답 결과 문자열
currentDateTime string Y 탐색 시점 시간 정보. ISO datetime format 사용
route key: option code
value: route unit ent array
Y 응답결과

Route Unit Ent

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

속성 타입 필수 여부 설명
summary summary Y 요약 정보
path lng-lat position format array Y 경로를 구성하는 모든 좌표열.해당 좌표들에는 0번부터 시작되는 index가 있으며, 이 index는 경로 정보를 표현하기 위한 pointIndex라는 명칭으로 활용됩니다.
section section unit N 해당 경로를 구성하는 주요 도로에 관한 정보열(모든 경로를 포함하는 정보는 아닙니다.)
guide guide unit for ent array N 안내 정보열

Summary

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

속성 타입 필수 여부 설명
start response position format Y 출발지
goal response position format Y 목적지
waypoints response position format 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 N 구간 혼잡도
speed int N 평균 속도

Guide Unit for Ent

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

속성 타입 필수 여부 설명
pointIndex int Y 경로를 구성하는 좌표의 인덱스
type guide code 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 - 길찾기 성공
200 1 - 출발지와 도착지가 동일
200 2 - 출발지 또는 도착지가 도로 주변이 아닌 경우
200 3 - 자동차 길찾기 결과 제공 불가
200 4 - 경유지가 도로 주변이 아닌 경우
200 5 - 요청 경로가 매우 긴 경우(경유지를 포함한 직선거리의 합이 1500km이상인 경우)

lng-lat Position Format

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

Response Position Format

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

속성 타입 필수 여부 설명
location lng-lat position Y 지점
dir view direction code 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

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

코드 설명
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.ntruss.com/map-direction/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
                    }
                ]
            }
        ]
    }
}
아쉬운 점이 있다면 이야기해 주세요.
0/5000
내용을 입력해 주세요
의견 보내기