페이지 이동경로
- 문서>
- 카카오내비>
- REST API
카카오내비
REST API
이 문서는 REST API를 사용하여 경로 안내 정보를 요청하는 방법을 안내합니다.
각 API를 통해 제공 받은 경로 정보는 웹 서비스나 애플리케이션에서 다양한 목적에 맞게 활용할 수 있습니다.
이 문서에 포함된 기능은 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.
자동차 길찾기
단일 출발지에서 단일 목적지까지의 경로 정보를 제공합니다. 최대 5개의 경유지를 추가할 수 있습니다.
REST API 키를 헤더에 담아 GET으로 요청합니다. 경유지나 경로 탐색과 관련한 설정과 운행 차량 정보를 지정할 수 있습니다.
성공 시 응답 바디에 JSON 객체로 설정한 목적지로 가는 경로 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Request
URL
GET /v1/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK ${REST_API_KEY}
Parameter
| Name | Type | Description | Required |
|---|---|---|---|
| origin | String |
출발지 다음 중 하나의 형식으로 요청: ${X좌표},${Y좌표},name=${출발지명}${X좌표},${Y좌표} (예: "127.111202,37.394912,name=판교역" 또는 "127.111202,37.394912") |
O |
| destination | String |
목적지 다음 중 하나의 형식으로 요청: ${X좌표},${Y좌표},name=${목적지명}${X좌표},${Y좌표}(예: "127.111202,37.394912,name=판교역" 또는 "127.111202,37.394912") |
O |
| waypoints | String |
경유지, 최대 5개까지 허용 경유지 수만큼 ${X좌표},${Y좌표},name=${경유지명} 또는 ${X좌표},${Y좌표}를 |(또는 인코딩된 문자인 %7C)로 연결하여 입력(예: "127.111202,37.394912,name=판교역 | 127.112275,37.392815") |
X |
| priority | String |
경로탐색 우선순위 옵션 다음 중 하나: RECOMMEND: 추천 경로TIME: 최단 시간DISTANCE: 최단 경로(기본값: RECOMMEND) |
X |
| avoid | String |
경로탐색 제한 옵션 다음 값 사용 가능: roadevent: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보)ferries: 페리 항로toll: 유료도로motorway: 자동차 전용도로schoolzone: 어린이보호구역(기본값: null)여러 개의 제한 옵션을 사용하려면 |(또는 인코딩된 문자인 %7C)로 연결(예: avoid=roadevent|ferries) |
X |
| alternatives | Boolean |
대안 경로 제공 여부true: 대안 경로 제공false: 대안 경로 미제공 (기본값: false) |
X |
| road_details | Boolean |
상세 도로 정보 제공 여부true: 상세 도로 정보 제공false: 상세 도로 정보 미제공(기본값: false) |
X |
| car_type | Int |
차종 (기본값: 1) |
X |
| car_fuel | String |
차량 유종 정보 다음 중 하나: GASOLINE: 휘발유DIESEL: 경유LPG: LPG(기본값: GASOLINE) |
X |
| car_hipass | Boolean |
하이패스 장착 여부true: 하이패스 장착false: 하이패스 미장착(기본값: false) |
X |
| summary | Boolean |
요약 정보 제공 여부true: 요약 정보 제공false: 요약 정보 미제공(기본값: false) |
X |
Response
| Name | Type | Description |
|---|---|---|
| trans_id | String |
경로 요청 ID |
| routes | Route[] |
경로 정보alternatives가 true인 경우 한 개 이상의 경로 제공 가능 |
Route: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| result_code | Int |
경로 탐색 결과 코드 |
| result_msg | String |
경로 탐색 결과 메시지 |
| summary | Summary |
경로 요약 정보 |
| sections | Section[] |
구간별 경로 정보 경유지가 존재할 경우 {경유지 수 + 1} 만큼의 섹션(경로 구간) 생성 (예: 경유지 수가 2개인 경우 총 3개의 섹션 정보가 생성, section1: 출발지 → 경유지 1 section2: 경유지1 → 경유지 2 section3: 경유지2 → 목적지) |
Summary: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| origin | Origin |
출발지 정보 |
| destination | Destination |
목적지 정보 |
| waypoints | Waypoint[] |
경유지 정보 |
| priority | String |
경로탐색 우선순위 옵션 |
| bound | Bound |
모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box) |
| fare | Fare |
요금 정보 |
| distance | Int |
전체 검색결과 거리(미터) |
| duration | Int |
목적지까지 소요시간(초) |
Section: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| distance | Int |
섹션 거리(미터) |
| duration | Int |
전체 검색결과 이동시간(초) |
| bound | Bound |
모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box) summary가 false인 경우에만 제공 |
| roads | Road[] |
도로 정보summary가 false인 경우에만 제공 |
| guides | Guide[] |
안내 정보summary가 false인 경우에만 제공 |
Origin: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| name | String |
출발지 이름 |
| x | Double |
X 좌표 |
| y | Double |
Y 좌표 |
Destination: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| name | String |
목적지 이름 |
| x | Double |
X 좌표 |
| y | Double |
Y 좌표 |
Waypoint: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| name | String |
경유지 이름 |
| x | Double |
X 좌표 |
| y | Double |
Y 좌표 |
Bound: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| min_x | Double |
바운딩 박스 왼쪽 하단의 X 좌표 |
| min_y | Double |
바운딩 박스 왼쪽 하단의 Y 좌표 |
| max_x | Double |
바운딩 박스 오른쪽 상단의 X 좌표 |
| max_y | Double |
바운딩 박스 오른쪽 상단의 Y 좌표 |
Fare: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| taxi | Int |
택시 요금(원) |
| toll | Int |
통행 요금(원) |
Road: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| name | String |
도로명 |
| distance | Int |
도로길이(미터) |
| duration | Int |
예상 이동시간(초) 현재 예상 이동시간 및 실제 이동시간은 동일한 값으로 설정 |
| traffic_speed | Double |
현재 교통정보 속도(km/h) |
| traffic_state | Int |
현재 교통정보 상태 |
| vertexes | Double[] |
X,Y 좌표로 구성된 1차원 배열 (예: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] ) |
Guide: 자동차 길찾기
| Name | Type | Description |
|---|---|---|
| name | String |
명칭 |
| x | Double |
X 좌표 |
| y | Double |
Y 좌표 |
| distance | Int |
이전 가이드 지점부터 현재 가이드 지점까지 거리(미터) |
| duration | Int |
이전 가이드 지점부터 현재 가이드 지점까지 시간(초) |
| type | Int |
안내 타입 |
| guidance | String |
안내 문구 |
| road_index | Int |
현재 가이드에 대한 링크 인덱스 |
Sample
Request
curl -v -X GET "https://apis-navi.kakaomobility.com/v1/directions?origin=127.11015314141542,37.39472714688412&destination=127.10824367964793,37.401937080111644&waypoints=&priority=RECOMMEND&car_fuel=GASOLINE&car_hipass=false&alternatives=false&road_details=false" \
-H "Authorization: KakaoAK ${REST_API_KEY}"
Response
{
"trans_id": "f368e6fad6f648a4b3e1c1680b0a6ff2",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"summary": {
"origin": {
"name": "",
"x": 127.11015051307636,
"y": 37.394725518530834
},
"destination": {
"name": "",
"x": 127.10823557165544,
"y": 37.401928707331656
},
"waypoints": [],
"priority": "RECOMMEND",
"bound": {
"min_x": 127.10833536148644,
"min_y": 37.39445954360996,
"max_x": 127.1098222529551,
"max_y": 37.40242724407785
},
"fare": {
"taxi": 3800,
"toll": 0
},
"distance": 1033,
"duration": 262
},
"sections": [
{
"distance": 1033,
"duration": 262,
"bound": {
"min_x": 127.10824109988312,
"min_y": 37.394469584427156,
"max_x": 127.10991634747967,
"max_y": 37.40242613861426
},
"roads": [
{
"name": "",
"distance": 22,
"duration": 5,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10991634747967,
37.39447145478345,
127.10966790676201,
37.394469584427156
]
},
{
"name": "판교역로",
"distance": 883,
"duration": 213,
"traffic_speed": 19.0,
"traffic_state": 2,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10967141980313,
37.39512739646385,
127.10967141980313,
37.39512739646385,
127.10968100356395,
37.396226781360426,
127.10968100356395,
37.396226781360426,
127.10967417816033,
37.39775855885587,
127.10967417816033,
37.39775855885587,
127.10968323318781,
37.39794785293074,
127.10968323318781,
37.39794785293074,
127.10967534594126,
37.39861458950405,
127.10967534594126,
37.39861458950405,
127.10967214334856,
37.399840028043634,
127.10967214334856,
37.399840028043634,
127.1096931266438,
37.40093048716485,
127.1096931266438,
37.40093048716485,
127.10967543155922,
37.40242613861426
]
},
{
"name": "판교역로241번길",
"distance": 128,
"duration": 44,
"traffic_speed": 25.0,
"traffic_state": 3,
"vertexes": [
127.10967543155922,
37.40242613861426,
127.10860261294675,
37.40240904474889,
127.10860261294675,
37.40240904474889,
127.10824109988312,
37.402415329497174
]
}
],
"guides": [
{
"name": "출발지",
"x": 127.10991634747967,
"y": 37.39447145478345,
"distance": 0,
"duration": 0,
"type": 100,
"guidance": "출발지",
"road_index": 0
},
{
"name": "",
"x": 127.10966790676201,
"y": 37.394469584427156,
"distance": 22,
"duration": 5,
"type": 2,
"guidance": "우회전",
"road_index": 1
},
{
"name": "",
"x": 127.10967543155922,
"y": 37.40242613861426,
"distance": 883,
"duration": 213,
"type": 1,
"guidance": "좌회전",
"road_index": 2
},
{
"name": "목적지",
"x": 127.10824109988312,
"y": 37.402415329497174,
"distance": 128,
"duration": 44,
"type": 101,
"guidance": "목적지",
"road_index": -1
}
]
}
]
}
]
}
다중 경유지 길찾기
단일 출발지에서 여러 개의 경유지를 거쳐 단일 목적지까지의 경로 정보를 제공합니다. 최대 5개의 경유지를 추가할 수 있는 자동차 길찾기와 달리, 다중 경유지 길찾기 요청 시에는 최대 30개의 경유지를 설정할 수 있습니다.
REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Type을 application/json으로 설정해야 합니다.
성공 시 응답 바디에 JSON 객체로 지정한 경유지를 거친 경로 정보를 받습니다. 응답 구성은 자동차 길찾기 응답과 동일합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Request
URL
POST /v1/waypoints/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
| Name | Type | Description | Required |
|---|---|---|---|
| origin | Origin |
출발지 | O |
| destination | Destination |
목적지 | O |
| waypoints | Waypoint[] |
경유지, 최대 30개까지 허용 | X |
| priority | String |
경로탐색 우선순위 옵션 다음 중 하나: RECOMMEND: 추천 경로TIME: 최단 시간DISTANCE: 최단 경로(기본값: RECOMMEND) |
X |
| avoid | String[] |
경로탐색 제한 옵션을 배열로 사용 다음 값 사용 가능: roadevent: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보)ferries: 페리 항로toll: 유료도로motorway: 자동차 전용도로schoolzone: 어린이보호구역 (예: ["roadevent", "motorway"])(기본값: null) |
X |
| alternatives | Boolean |
대안 경로 제공 여부true: 대안 경로 제공false: 대안 경로 미제공 (기본값: false) |
X |
| road_details | Boolean |
상세 도로 정보 제공 여부true: 상세 도로 정보 제공false: 상세 도로 정보 미제공(기본값: false) |
X |
| car_type | Int |
차종 (기본값: 1) |
X |
| car_fuel | String |
차량 유종 정보 다음 중 하나: GASOLINE: 휘발유DIESEL: 경유LPG: LPG(기본값: GASOLINE) |
X |
| car_hipass | Boolean |
하이패스 장착 여부true: 하이패스 장착false: 하이패스 미장착(기본값: false) |
X |
| summary | Boolean |
요약 정보 제공 여부true: 요약 정보 제공false: 요약 정보 미제공(기본값: false) |
X |
Origin: 다중 경유지 길찾기
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
출발지 이름 | X |
| x | Double |
X 좌표 | O |
| y | Double |
Y 좌표 | O |
Destination: 다중 경유지 길찾기
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
목적지 이름 | X |
| x | Double |
X 좌표 | O |
| y | Double |
Y 좌표 | O |
Waypoint: 다중 경유지 길찾기
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
경유지 이름 | X |
| x | Double |
X 좌표 | O |
| y | Double |
Y 좌표 | O |
Response
응답 구성은 자동차 길찾기와 동일합니다.
Sample
Request
curl -v -X POST "https://apis-navi.kakaomobility.com/v1/waypoints/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-d '{
"origin": {
"x": "127.11024293202674",
"y": " 37.394348634049784"
},
"destination": {
"x": "127.10860518470294",
"y": "37.401999820065534"
},
"waypoints": [
{
"name": "name0",
"x": 127.11341936045922,
"y": 37.39639094915999
}
],
"priority": "RECOMMEND",
"car_fuel": "GASOLINE",
"car_hipass": false,
"alternatives": false,
"road_details": false
}'
Response
{
"trans_id": "eba67ee00e494638984205a83ba3892a",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"summary": {
"origin": {
"name": "",
"x": 127.11023403583478,
"y": 37.39434769502827
},
"destination": {
"name": "",
"x": 127.10859622855493,
"y": 37.40199450213265
},
"waypoints": [
{
"name": "name0",
"x": 127.11341740484119,
"y": 37.39639001677204
}
],
"priority": "RECOMMEND",
"bound": {
"min_x": 127.10869672963145,
"min_y": 37.39446226802707,
"max_x": 127.11400101911747,
"max_y": 37.402458630852735
},
"fare": {
"taxi": 4300,
"toll": 0
},
"distance": 1772,
"duration": 549
},
"sections": [
{
"distance": 605,
"duration": 164,
"bound": {
"min_x": 127.11341931516797,
"min_y": 37.394469584427156,
"max_x": 127.11406301821938,
"max_y": 37.39623266200683
},
"roads": [
{
"name": "",
"distance": 22,
"duration": 5,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10991634747967,
37.39447145478345,
127.10966790676201,
37.394469584427156
]
},
{
"name": "판교역로",
"distance": 195,
"duration": 54,
"traffic_speed": 13.0,
"traffic_state": 2,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10967141980313,
37.39512739646385,
127.10967141980313,
37.39512739646385,
127.10968100356395,
37.396226781360426
]
},
{
"name": "대왕판교로606번길",
"distance": 331,
"duration": 93,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.10968100356395,
37.396226781360426,
127.11030222640413,
37.39622244643168,
127.11030222640413,
37.39622244643168,
127.11047162177373,
37.396223720873245,
127.11047162177373,
37.396223720873245,
127.11126224002652,
37.39622065509858,
127.11126224002652,
37.39622065509858,
127.11205275202975,
37.396226593999046,
127.11205275202975,
37.396226593999046,
127.11225602658233,
37.39622812029087,
127.11225602658233,
37.39622812029087,
127.11274162696445,
37.39623176501827,
127.11274162696445,
37.39623176501827,
127.11309181718316,
37.39622538141045,
127.11309181718316,
37.39622538141045,
127.11341931516797,
37.39622783738649
]
},
{
"name": "대왕판교로606번길",
"distance": 57,
"duration": 12,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11341931516797,
37.39622783738649,
127.11406301821938,
37.39623266200683
]
}
],
"guides": [
{
"name": "출발지",
"x": 127.10991634747967,
"y": 37.39447145478345,
"distance": 0,
"duration": 0,
"type": 100,
"guidance": "출발지",
"road_index": 0
},
{
"name": "",
"x": 127.10966790676201,
"y": 37.394469584427156,
"distance": 22,
"duration": 5,
"type": 2,
"guidance": "우회전",
"road_index": 1
},
{
"name": "동안사거리",
"x": 127.10968100356395,
"y": 37.396226781360426,
"distance": 195,
"duration": 54,
"type": 2,
"guidance": "분당구청 삼평동주민센터 방면으로 우회전",
"road_index": 2
},
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 331,
"duration": 93,
"type": 1000,
"guidance": "경유지",
"road_index": -1
}
]
},
{
"distance": 1224,
"duration": 397,
"bound": {
"min_x": 127.10860261294675,
"min_y": 37.39622783738649,
"max_x": 127.11406301821938,
"max_y": 37.40242613861426
},
"roads": [
{
"name": "대왕판교로606번길",
"distance": 57,
"duration": 12,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11341931516797,
37.39622783738649,
127.11406301821938,
37.39623266200683
]
},
{
"name": "",
"distance": 233,
"duration": 57,
"traffic_speed": 42.0,
"traffic_state": 0,
"vertexes": [
127.11406301821938,
37.39623266200683,
127.11403422576758,
37.39771922184463,
127.11403422576758,
37.39771922184463,
127.11404960021814,
37.398332068681995
]
},
{
"name": "동판교로177번길",
"distance": 86,
"duration": 45,
"traffic_speed": 21.0,
"traffic_state": 3,
"vertexes": [
127.11404960021814,
37.398332068681995,
127.1130784782746,
37.3983157776669
]
},
{
"name": "분당내곡로",
"distance": 160,
"duration": 27,
"traffic_speed": 33.0,
"traffic_state": 3,
"vertexes": [
127.1130784782746,
37.3983157776669,
127.11313041857109,
37.39965877010523,
127.11313041857109,
37.39965877010523,
127.11312925062586,
37.399757879664605
]
},
{
"name": "대왕판교로644번길",
"distance": 124,
"duration": 76,
"traffic_speed": 15.0,
"traffic_state": 2,
"vertexes": [
127.11312925062586,
37.399757879664605,
127.11274420726458,
37.39984509856906,
127.11274420726458,
37.39984509856906,
127.11173886656147,
37.39985557194009
]
},
{
"name": "",
"distance": 564,
"duration": 180,
"traffic_speed": 16.0,
"traffic_state": 2,
"vertexes": [
127.11173886656147,
37.39985557194009,
127.11175987981302,
37.40094603107842,
127.11175987981302,
37.40094603107842,
127.11174254485269,
37.40241465350646,
127.11170855662199,
37.402423408918274,
127.10967543155922,
37.40242613861426,
127.10967543155922,
37.40242613861426,
127.10860261294675,
37.40240904474889,
127.10860261294675,
37.40240904474889,
127.10860261294675,
37.40240904474889
]
}
],
"guides": [
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 0,
"duration": 0,
"type": 0,
"guidance": "동판교로 삼평동주민센터 방면으로 직진",
"road_index": 0
},
{
"name": "",
"x": 127.11406301821938,
"y": 37.39623266200683,
"distance": 57,
"duration": 12,
"type": 1,
"guidance": "삼평동주민센터 방면으로 좌회전",
"road_index": 1
},
{
"name": "",
"x": 127.11404960021814,
"y": 37.398332068681995,
"distance": 233,
"duration": 57,
"type": 1,
"guidance": "판교테크노밸리 양재 내곡 방면으로 좌회전",
"road_index": 2
},
{
"name": "",
"x": 127.1130784782746,
"y": 37.3983157776669,
"distance": 86,
"duration": 45,
"type": 2,
"guidance": "동판교IC 내곡,서울 방면으로 우회전",
"road_index": 3
},
{
"name": "삼평사거리",
"x": 127.11312925062586,
"y": 37.399757879664605,
"distance": 160,
"duration": 27,
"type": 1,
"guidance": "대왕판교로 경기창조경제혁신센터 방면으로 좌회전",
"road_index": 4
},
{
"name": "",
"x": 127.11173886656147,
"y": 37.39985557194009,
"distance": 124,
"duration": 76,
"type": 2,
"guidance": "우회전",
"road_index": 5
},
{
"name": "목적지",
"x": 127.10860261294675,
"y": 37.40240904474889,
"distance": 564,
"duration": 180,
"type": 101,
"guidance": "목적지",
"road_index": -1
}
]
}
]
}
]
}
다중 출발지 길찾기
한 개 이상의 다중 출발지에서 단일 목적지까지의 경로 요약 정보를 제공합니다. 경로의 요약 정보만을 제공하기 때문에 상세 경로 안내를 받으려면 자동차 길찾기를 추가적으로 요청하여야 합니다.
출발지는 최대 30개까지 설정할 수 있습니다. 30개를 초과하는 출발지를 설정하려면 partnership@kakaomobility.com을 통해 제휴를 신청합니다.
REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Type을 application/json으로 설정해야 합니다.
성공 시 응답 바디에 JSON 객체로 경로 요약 정보를 받습니다. 경로 요약 정보는 여러 개의 출발지에서 하나의 목적지로 가는 경로 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Request
URL
POST /v1/origins/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
| Name | Type | Description | Required |
|---|---|---|---|
| origins | Origin[] |
출발지, 최대 30개까지 허용 | O |
| destination | Destination |
목적지 | O |
| radius | Int |
길찾기 반경(미터) (최대: 10000) |
O |
| priority | String |
경로탐색 우선순위 옵션 다음 중 하나: TIME: 최단 시간DISTANCE: 최단 경로(기본값: TIME) |
X |
| avoid | String[] |
경로탐색 제한 옵션을 배열로 사용 다음 값 사용 가능: roadevent: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보)ferries: 페리 항로toll: 유료도로motorway: 자동차 전용도로schoolzone: 어린이보호구역(예: ["roadevent", "motorway"])(기본값: null) |
X |
Origin: 다중 출발지 길찾기
| Name | Type | Description | Required |
|---|---|---|---|
| key | String |
각 출발지를 구분하기 위한 임의의 문자열 지정 | O |
| x | Double |
X 좌표 | O |
| y | Double |
Y 좌표 | O |
Destination: 다중 출발지 길찾기
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
목적지 이름 | X |
| x | Double |
X 좌표 | O |
| y | Double |
Y 좌표 | O |
Response
| Name | Type | Description |
|---|---|---|
| trans_id | String |
경로 요청 ID |
| routes | Route[] |
경로 정보, 경로 수 만큼 생성 |
Route: 다중 출발지 길찾기
| Name | Type | Description |
|---|---|---|
| result_code | Int |
경로 탐색 결과 코드 |
| result_msg | String |
경로 탐색 결과 메시지 |
| key | String |
origins의 key 값으로 지정한 각 출발지의 키 값 |
| summary | Summary |
경로 요약 정보 |
Summary: 다중 출발지 길찾기
| Name | Type | Description |
|---|---|---|
| distance | Int |
전체 검색결과 거리(미터) |
| duration | Int |
목적지까지 소요시간(초) |
Sample
Request
curl -v -X POST "https://apis-navi.kakaomobility.com/v1/origins/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-d '{
"origins": [
{
"x": "127.1331694942593",
"y": "37.4463137562622",
"key": "0"
},
{
"x": "127.13243772760565",
"y": "37.44148514309502",
"key": "1"
}
],
"destination": {
"x": "127.14816492905383",
"y": "37.4401690139602"
},
"radius": 5000
}'
Response
{
"trans_id": "a2653095f26445dba15d736c5714d86a",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"key": "0",
"summary": {
"distance": 2305,
"duration": 615
}
},
{
"result_code": 0,
"result_msg": "길찾기 성공",
"key": "1",
"summary": {
"distance": 1878,
"duration": 408
}
}
]
}
다중 목적지 길찾기
단일 출발지에서 한 개 이상의 다중 목적지까지의 경로 요약 정보를 제공합니다. 경로의 요약 정보만을 제공하기 때문에 상세 경로 안내를 받으려면 자동차 길찾기를 추가적으로 요청하여야 합니다.
목적지는 최대 30개까지 설정할 수 있습니다. 30개를 초과하는 목적지를 설정하려면 partnership@kakaomobility.com을 통해 제휴를 신청합니다.
REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Type을 application/json으로 설정해야 합니다.
성공 시 응답 바디에 JSON 객체로 경로 요약 정보를 받습니다. 경로 요약 정보는 하나의 출발지에서 여러 목적지로 가는 경로 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Request
URL
POST /v1/destinations/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
| Name | Type | Description | Required |
|---|---|---|---|
| origin | Origin |
출발지 | O |
| destinations | Destination[] |
목적지, 최대 30개까지 허용 | O |
| radius | Int |
길찾기 반경(미터) (최대: 10000) |
O |
| priority | String |
경로탐색 우선순위 옵션 다음 중 하나: TIME: 최단 시간DISTANCE: 최단 경로(기본값: TIME) |
X |
| avoid | String[] |
경로탐색 제한 옵션을 배열로 사용 다음 값 사용 가능: roadevent: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보)ferries: 페리 항로toll: 유료도로motorway: 자동차 전용도로schoolzone: 어린이보호구역(예: ["roadevent", "motorway"])(기본값: null) |
X |
Origin: 다중 목적지 길찾기
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
출발지 이름 | X |
| x | Double |
X 좌표 | O |
| y | Double |
Y 좌표 | O |
Destination: 다중 목적지 길찾기
| Name | Type | Description | Required |
|---|---|---|---|
| key | String |
각 목적지를 구분하기 위한 임의의 문자열 지정 O | |
| x | Double |
X 좌표 | O |
| y | Double |
Y 좌표 | O |
Response
| Name | Type | Description |
|---|---|---|
| trans_id | String |
경로 요청 ID |
| routes | Route[] |
경로 정보, 경로 수 만큼 생성 |
Route: 다중 목적지 길찾기
| Name | Type | Description |
|---|---|---|
| result_code | Int |
경로 탐색 결과 코드 |
| result_msg | String |
경로 탐색 결과 메시지 |
| key | String |
destinations의 key 값으로 지정한 각 목적지의 키 값 |
| summary | Summary |
경로 요약 정보 |
Summary: 다중 목적지 길찾기
| Name | Type | Description |
|---|---|---|
| distance | Int |
전체 검색결과 거리(미터) |
| duration | Int |
목적지까지 소요시간(초) |
Sample
Request
curl -v -X POST "https://apis-navi.kakaomobility.com/v1/destinations/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-d '{
"origin": {
"x": "127.13144306487084",
"y": " 37.44134209110179"
},
"destinations": [
{
"x": "127.14112393388389",
"y": "37.44558371517034",
"key": "0"
},
{
"x": "127.14192737519186",
"y": "37.4401766683372",
"key": "1"
}
],
"radius": 5000
}'
Response
{
"trans_id": "b2520cb429004460a4d5f389d108db38",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"key": "0",
"summary": {
"distance": 1307,
"duration": 307
}
},
{
"result_code": 0,
"result_msg": "길찾기 성공",
"key": "1",
"summary": {
"distance": 1323,
"duration": 320
}
}
]
}
미래운행정보 길찾기
미래의 특정 시간을 지정하여 해당 시간을 기준으로 단일 출발지에서 단일 목적지까지의 경로 정보를 제공합니다. 반드시 현재 시각 이후로 출발 시간을 지정해야 합니다.
REST API 키를 헤더에 담아 GET으로 요청합니다.
성공 시 응답 바디에 JSON 객체로 경로 정보를 받습니다. 경로 정보는 지정한 출발 시간에 하나의 출발지에서 하나의 목적지로 가는 예상 경로 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
Request
URL
GET /v1/future/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK ${REST_API_KEY}
Parameter
| Name | Type | Description | Required |
|---|---|---|---|
| departure_time | String |
출발시간, YYYYMMDDHHMM 형식으로 현재시간 이후 시간 설정 (예: 202107171010) |
O |
| origin | String |
출발지 다음 중 하나의 형식으로 요청: ${X좌표},${Y좌표},name=${출발지명}${X좌표},${Y좌표} (예: "127.111202,37.394912,name=판교역" 또는 "127.111202,37.394912") |
O |
| destination | String |
목적지 다음 중 하나의 형식으로 요청: ${X좌표},${Y좌표},name=${목적지명}${X좌표},${Y좌표}(예: "127.111202,37.394912,name=판교역" 또는 "127.111202,37.394912") |
O |
| waypoints | String |
경유지, 최대 5개까지 허용 경유지 수만큼 ${X좌표},${Y좌표},name=${경유지명} 또는 ${X좌표},${Y좌표}를 |(또는 인코딩된 문자인 %7C)로 연결하여 입력(예: "127.111202,37.394912,name=판교역 | 127.112275,37.392815") |
X |
| priority | String |
경로탐색 우선순위 옵션 다음 중 하나: RECOMMEND: 추천 경로TIME: 최단 시간DISTANCE: 최단 경로(기본값: RECOMMEND) |
X |
| avoid | String |
경로탐색 제한 옵션 다음 값 사용 가능: roadevent: 유고 정보(교통사고, 행사, 재난, 도로 공사 등의 교통 장애 정보)ferries: 페리 항로toll: 유료도로motorway: 자동차 전용도로schoolzone: 어린이보호구역(기본값: null)여러 개의 제한 옵션을 사용하려면 |(또는 인코딩된 문자인 %7C)로 연결(예: avoid=roadevent|ferries) |
X |
| alternatives | Boolean |
대안 경로 제공 여부true: 대안 경로 제공false: 대안 경로 미제공 (기본값: false) |
X |
| road_details | Boolean |
상세 도로 정보 제공 여부true: 상세 도로 정보 제공false: 상세 도로 정보 미제공(기본값: false) |
X |
| car_type | Int |
차종 (기본값: 1) |
X |
| car_fuel | String |
차량 유종 정보 다음 중 하나: GASOLINE: 휘발유DIESEL: 경유LPG: LPG(기본값: GASOLINE) |
X |
| car_hipass | Boolean |
하이패스 장착 여부true: 하이패스 장착false: 하이패스 미장착(기본값: false) |
X |
| summary | Boolean |
요약 정보 제공 여부true: 요약 정보 제공false: 요약 정보 미제공(기본값: false) |
X |
Response
응답 구성은 자동차 길찾기와 동일합니다.
Sample
Request
curl -v -X GET "https://apis-navi.kakaomobility.com/v1/future/directions?origin=127.11015314141542,37.39472714688412&destination=127.10824367964793,37.401937080111644&departure_time=202109170000" \
-H "Authorization: KakaoAK ${REST_API_KEY}"
Response
{
"trans_id": "e173a5282b084871bfbfac8771743748",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"summary": {
"origin": {
"name": "",
"x": 127.11015051307636,
"y": 37.394725518530834
},
"destination": {
"name": "",
"x": 127.10823557165544,
"y": 37.401928707331656
},
"waypoints": [],
"priority": "RECOMMEND",
"bound": {
"min_x": 127.10833536148644,
"min_y": 37.39445954360996,
"max_x": 127.1098222529551,
"max_y": 37.40242724407785
},
"fare": {
"taxi": 3800,
"toll": 0
},
"distance": 1033,
"duration": 255
},
"sections": [
{
"distance": 1033,
"duration": 255,
"bound": {
"min_x": 127.10824109988312,
"min_y": 37.394469584427156,
"max_x": 127.10991634747967,
"max_y": 37.40242613861426
},
"roads": [
{
"name": "",
"distance": 22,
"duration": 5,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10991634747967,
37.39447145478345,
127.10966790676201,
37.394469584427156
]
},
{
"name": "판교역로",
"distance": 883,
"duration": 206,
"traffic_speed": 20.0,
"traffic_state": 3,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10967141980313,
37.39512739646385,
127.10967141980313,
37.39512739646385,
127.10968100356395,
37.396226781360426,
127.10968100356395,
37.396226781360426,
127.10967417816033,
37.39775855885587,
127.10967417816033,
37.39775855885587,
127.10968323318781,
37.39794785293074,
127.10968323318781,
37.39794785293074,
127.10967534594126,
37.39861458950405,
127.10967534594126,
37.39861458950405,
127.10967214334856,
37.399840028043634,
127.10967214334856,
37.399840028043634,
127.1096931266438,
37.40093048716485,
127.1096931266438,
37.40093048716485,
127.10967543155922,
37.40242613861426
]
},
{
"name": "판교역로241번길",
"distance": 128,
"duration": 44,
"traffic_speed": 25.0,
"traffic_state": 3,
"vertexes": [
127.10967543155922,
37.40242613861426,
127.10860261294675,
37.40240904474889,
127.10860261294675,
37.40240904474889,
127.10824109988312,
37.402415329497174
]
}
],
"guides": [
{
"name": "출발지",
"x": 127.10991634747967,
"y": 37.39447145478345,
"distance": 0,
"duration": 0,
"type": 100,
"guidance": "출발지",
"road_index": 0
},
{
"name": "",
"x": 127.10966790676201,
"y": 37.394469584427156,
"distance": 22,
"duration": 5,
"type": 2,
"guidance": "우회전",
"road_index": 1
},
{
"name": "",
"x": 127.10967543155922,
"y": 37.40242613861426,
"distance": 883,
"duration": 206,
"type": 1,
"guidance": "좌회전",
"road_index": 2
},
{
"name": "목적지",
"x": 127.10824109988312,
"y": 37.402415329497174,
"distance": 128,
"duration": 44,
"type": 101,
"guidance": "목적지",
"road_index": -1
}
]
}
]
}
]
}
레퍼런스
길찾기 API에서 사용하는 공통 클래스 정보를 안내합니다.
result_code: 경로 탐색 결과 코드
| Code | Description |
|---|---|
| 0 | 길찾기 성공 |
| 1 | 길찾기 결과를 찾을 수 없음 |
| 101 | 경유지 지점 주변의 도로를 탐색할 수 없음 |
| 102 | 시작 지점 주변의 도로를 탐색할 수 없음 |
| 103 | 도착 지점 주변의 도로를 탐색할 수 없음 |
| 104 | 출발지와 도착지가 같은 지점임 |
| 105 | 시작 지점 주변의 도로에 유고 정보(교통 장애)가 있음 |
| 106 | 도착 지점 주변의 도로에 유고 정보(교통 장애)가 있음 |
| 107 | 경유지 주변의 도로에 유고 정보(교통 장애)가 있음result_message에 경유지의 순번이 표시되며 번호는 1번부터 시작함예시) result_code: 107result_message: 경유지에 유고 정보 존재: 1번 경유지 |
| 201 | 다중 출발지: 출발지가 탐색영역에 포함되지 않음 |
| 202 | 다중 출발지: 출발지 최대 개수 초과 도로 선택 실패 |
| 203 | 다중 출발지: 목적지 도로 선택 실패 |
| 204 | 다중 출발지: 경로탐색 처리시간 제한 |
| 205 | 다중 출발지: 출발지 주변의 유고 정보(교통 장애)로 인한 통행 불가 |
| 206 | 다중 출발지: 목적지 주변의 유고 정보(교통 장애)로 인한 통행 불가 |
| 207 | 다중 출발지: 출발지가 설정한 길찾기 반경 범위를 벗어남 |
| 301 | 다중 목적지: 출발지 도로 선택 실패 |
| 302 | 다중 목적지: 목적지 도로 선택 실패 |
| 303 | 다중 목적지: 목적지 최대 개수 초과로 인해 경로 탐색 실패 |
| 304 | 다중 목적지:목적지가 설정한 길찾기 반경 범위를 벗어남 |
traffic_state: 현재 교통정보 상태
| Code | Description |
|---|---|
| 0 | 교통 상태 정보 없음 |
| 1 | 교통 정체 |
| 2 | 교통 지체 |
| 3 | 교통 서행 |
| 4 | 교통 원활 |
| 6 | 교통사고(통행불가) |
car_type: 차종
| Code | Description |
|---|---|
| 1 | 소형 (예: 승용차, 16인승 이하 승합차, 2.5ton 미만 화물차) 분류기준: 2축 차량, 윤폭 279.4mm 이하 |
| 2 | 중형 (예: 승합차 17-32인승, 2.5~5.5ton 화물차) 분류기준: 2축 차량, 윤폭 279.4mm 초과, 윤거 1,800mm 이하 |
| 3 | 대형 (예: 승합차 33인승 이상, 5.5~10ton 화물차) 분류기준: 2축 차량, 윤폭 279.4mm 초과, 윤거 1,800mm 초과 |
| 4 | 대형화물 (예: 10t~20ton 화물차) 분류기준: 3축 차량 |
| 5 | 특수화물 (예: 20t 이상 화물차) 분류기준: 4축 이상 차량 |
| 6 | 경차 분류기준: 배기량이 1,000cc 미만으로 길이 3.6m, 너비 1.6m, 높이 2.0m 이하인 차량 |
| 7 | 이륜차 |
type: 안내 타입
| Code | Description |
|---|---|
| 0 | 직진 |
| 1 | 좌회전 |
| 2 | 우회전 |
| 3 | 유턴 |
| 5 | 왼쪽 방향 |
| 6 | 오른쪽 방향 |
| 7 | 고속도로 출구 |
| 8 | 왼쪽에 고속도로 출구 |
| 9 | 오른쪽에 고속도로 출구 |
| 10 | 고속도로 입구 |
| 11 | 왼쪽에 고속도로 입구 |
| 12 | 오른쪽에 고속도로 입구 |
| 14 | 고가도로 진입 |
| 15 | 지하차도 진입 |
| 16 | 고가도로 옆길 |
| 17 | 지하차도 옆길 |
| 18 | 오른쪽 1시 방향 |
| 19 | 오른쪽 2시 방향 |
| 20 | 오른쪽 3시 방향 |
| 21 | 오른쪽 4시 방향 |
| 22 | 오른쪽 5시 방향 |
| 23 | 6시 방향 |
| 24 | 왼쪽 7시 방향 |
| 25 | 왼쪽 8시 방향 |
| 26 | 왼쪽 9시 방향 |
| 27 | 왼쪽 10시 방향 |
| 28 | 왼쪽 11시 방향 |
| 29 | 12시 방향 |
| 30 | 로터리에서 오른쪽 1시 방향 |
| 31 | 로터리에서 오른쪽 2시 방향 |
| 32 | 로터리에서 오른쪽 3시 방향 |
| 33 | 로터리에서 오른쪽 4시 방향 |
| 34 | 로터리에서 오른쪽 5시 방향 |
| 35 | 로터리에서 6시 방향 |
| 36 | 로터리에서 왼쪽 7시 방향 |
| 37 | 로터리에서 왼쪽 8시 방향 |
| 38 | 로터리에서 왼쪽 9시 방향 |
| 39 | 로터리에서 왼쪽 10시 방향 |
| 40 | 로터리에서 왼쪽 11시 방향 |
| 41 | 로터리에서 12시 방향 |
| 42 | 도시고속도로 출구 |
| 43 | 왼쪽에 도시고속도로 출구 |
| 44 | 오른쪽에 도시고속도로 출구 |
| 45 | 도시고속도로 입구 |
| 46 | 왼쪽에 도시고속도로 입구 |
| 47 | 오른쪽에 도시고속도로 입구 |
| 48 | 왼쪽 고속도로 진입 |
| 49 | 오른쪽 고속도로 진입 |
| 61 | 페리항로 진입 |
| 62 | 페리항로 진출 |
| 70 | 회전교차로에서 오른쪽 1시 방향 |
| 71 | 회전교차로에서 오른쪽 2시 방향 |
| 72 | 회전교차로에서 오른쪽 3시 방향 |
| 73 | 회전교차로에서 오른쪽 4시 방향 |
| 74 | 회전교차로에서 오른쪽 5시 방향 |
| 75 | 회전교차로에서 6시 방향 |
| 76 | 회전교차로에서 왼쪽 7시 방향 |
| 77 | 회전교차로에서 왼쪽 8시 방향 |
| 78 | 회전교차로에서 왼쪽 9시 방향 |
| 79 | 회전교차로에서 왼쪽 10시 방향 |
| 80 | 회전교차로에서 왼쪽 11시 방향 |
| 81 | 회전교차로에서 12시 방향 |
| 82 | 왼쪽 직진 |
| 83 | 오른쪽 직진 |
| 84 | 톨게이트 진입 |
| 85 | 원톨링 진입 |
| 86 | 분기 후 합류 구간 진입 |
| 100 | 출발지 |
| 101 | 목적지 |
| 1000 | 경유지 |
| 300 | 톨게이트 |
| 301 | 휴게소 |