- 인쇄
- PDF
driving
- 인쇄
- PDF
개요
길찾기 API는 지도 앱 메인 화면에서 주요 지역까지의 소요 시간과 거리, 예상 유류비, 통행 요금 정보를 제공합니다.
그리고 경로상 분기점에서 안내가 필요한 경우 해당 지점에서의 guide code를 제공합니다.
요청
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 | Y | 출발지 |
goal | multiple request position format | Y | - 목적지 하나 이상의 목적지 정보를 전달할 수 있으며, 복수 개의 목적지를 입력할 때는 : 로 연결입력한 목적지 정보 중 가장 적은 비용으로 도달할 수 있는 목적지로 경로가 생성됨 목적지의 최대 개수는 10개이며, 최초의 최적 목적지 좌표를 기준으로 직선거리 3km 이내의 좌표만 유효하게 판정 |
waypoints | multiple request position format list | N | - 경유지. 최대 15개를 입력할 수 있으며 서로 다른 경유지의 구분자로 |(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 인코딩이 필요합니다.
- 옵션 항목 간의 순서는 상관 없습니다.
다음은 request position format의 사용 예입니다.
- 기본 예:
127.12345,37.12345
- 이름 옵션 항목을 추가한 예:
127.12345,37.12345,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,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 여러 개를 |
문자로 연결한 리스트 문자열입니다. 경유지 파라미터인 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 IDX-NCP-APIGW-API-KEY-ID:{Client ID} |
X-NCP-APIGW-API-KEY | 앱 등록 시 발급 받은 Client SecretX-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
도로의 종별 및 실제 통행 속도 정보를 이용해 추정한 혼잡도 분류 코드입니다.
코드 | 설명 |
---|---|
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
}
]
}
]
}
}