페이지 이동경로
- Docs>
- Kakao Navi
Kakao Navi
REST API
This document describes how to request the directions in your service using a REST API. You can utilize the route data obtained through the Directions API in your web service or application depending on a specific purpose.
You can test the features described in this document in [Tools] > [REST API Test].
Directions for driving
Basic information
| Method | URL | Authorization |
|---|---|---|
GET |
https://apis-navi.kakaomobility.com/v1/directions |
REST API key |
| Permission | Prerequisite | Kakao Login | User consent |
|---|---|---|---|
| - | - | - | - |
This API provides route data from an origin to a destination. You can add up to 5 waypoints.
Add your REST API key to the request header, and send a GET request. You can set waypoints, navigation options or vehicle information.
If your request is successful, the API returns route data to the specified destination in JSON format. If failed, see Response code and error code to check its failure cause.
Request
Header
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_KEY}REST API key as a type of user authentication. |
O |
Query parameter
| Name | Type | Description | Required |
|---|---|---|---|
| origin | String |
Departure point. Use either format: - {X coordinate},{Y coordinate},name={origin name}- {X coordinate},{Y coordinate} (Example: "127.111202,37.394912,name=판교역" or "127.111202,37.394912") |
O |
| destination | String |
Arrival point. Use either format: - {X coordinate},{Y coordinate},name={destination name}- {X coordinate},{Y coordinate}(Example: "127.111202,37.394912,name=판교역" or "127.111202,37.394912") |
O |
| waypoints | String |
Stop point along the route. Up to 5 waypoints are allowed. For multiple waypoints, add | (or URL encoded character %7C) as many as the number of waypoints in either format:- {X coordinate},{Y coordinate},name={waypoint name} - {X coordinate},{Y coordinate} |
X |
| priority | String |
Set priority options for navigation. Use one of the followings: - RECOMMEND: Recommended route.- TIME: Fastest route.- DISTANCE: Shortest route.(Default: RECOMMEND) |
X |
| avoid | String |
Set limitation options for navigation. Use one or more among the followings: - roadevent: Exclude routes with traffic congestion due to accidents, events, disasters, or roadworks.- ferries: Exclude sea route.- toll: Exclude toll road.- motorway: Exclude motorway.- schoolzone: Exclude school zone.(Default: null)For multiple options, add | (or URL encoded character %7C) between options.(Example: avoid=roadevent|ferries) |
X |
| alternatives | Boolean |
Whether to provide alternative routes. - true: Provided. - false: Not provided. (Default: false) |
X |
| road_details | Boolean |
Whether to provide detailed road information. - true: Provided. - false: Not provided.(Default: false) |
X |
| car_type | Int |
Car type (Default: 1) |
X |
| car_fuel | String |
Fuel type. Use one of the followings: - GASOLINE: Gasoline - DIESEL: Diesel - LPG: LPG(Default: GASOLINE) |
X |
| car_hipass | Boolean |
Whether or not the Hi-pass system is used. - true: Using.- false: Not using.(Default: false) |
X |
| summary | Boolean |
Whether to provide summary for the routes. - true: Provided. - false: Not provided.(Default: false) |
X |
Response
Body
| Name | Type | Description |
|---|---|---|
| trans_id | String |
Unique identifier of a direction request. |
| routes | Route[] |
Route data. If alternatives is set to true, one or more routes are returned. |
Route: Directions for driving
| Name | Type | Description |
|---|---|---|
| result_code | Int |
Result code of directions search. |
| result_msg | String |
Result message of directions search. |
| summary | Summary |
Summary information of directions. |
| sections | Section[] |
Route data by section. If waypoints are specified, sections are created as many as {number of waypoints + 1}. (Example: If the number of waypoints is two, three sections are created. section1: origin → waypoint1 section2: waypoint1 → waypoint2 section3: waypoint2 → destination) |
Summary: Directions for driving
| Name | Type | Description |
|---|---|---|
| origin | Origin |
Origin information. |
| destination | Destination |
Destination information. |
| waypoints | Waypoint[] |
Waypoint information. |
| priority | String |
Set priority options for navigation. |
| bound | Bound |
Geo-bounding box that includes all routes. |
| fare | Fare |
Total fare. |
| distance | Int |
Total distance in meters. |
| duration | Int |
Travel time to the destination in seconds. |
Section: Directions for driving
| Name | Type | Description |
|---|---|---|
| distance | Int |
Distance between sections in meters. |
| duration | Int |
Total required time in seconds. |
| bound | Bound |
Geo-bounding box that includes all routes. Only returned if summary is set to false. |
| roads | Road[] |
Road information. Only returned if summary is set to false. |
| guides | Guide[] |
Guidance information. Only returned if summary is set to false. |
Origin: Directions for driving
| Name | Type | Description |
|---|---|---|
| name | String |
Origin name. |
| x | Double |
X coordinate (longitude). |
| y | Double |
Y coordinate (latitude). |
Destination: Directions for driving
| Name | Type | Description |
|---|---|---|
| name | String |
Destination name. |
| x | Double |
X coordinate (longitude). |
| y | Double |
Y coordinate (latitude). |
Waypoint: Directions for driving
| Name | Type | Description |
|---|---|---|
| name | String |
Waypoint name. |
| x | Double |
X coordinate (longitude). |
| y | Double |
Y coordinate (latitude). |
Bound: Directions for driving
| Name | Type | Description |
|---|---|---|
| min_x | Double |
X coordinate of the bottom left corner of the geo-bounding box. |
| min_y | Double |
Y coordinate of the bottom left corner of the geo-bounding box. |
| max_x | Double |
X coordinate of the top right corner of the geo-bounding box. |
| max_y | Double |
Y coordinate of the top right corner of the geo-bounding box. |
Fare: Directions for driving
| Name | Type | Description |
|---|---|---|
| taxi | Int |
Taxi fare in South Korean won (KRW). |
| toll | Int |
Toll fare in South Korean won (KRW). |
Road: Directions for driving
| Name | Type | Description |
|---|---|---|
| name | String |
Road name. |
| distance | Int |
Road distance in meters. |
| duration | Int |
Estimated travel time in seconds, which is considered as the actual required time. |
| traffic_speed | Double |
Current traffic speed in kilometers per hour. |
| traffic_state | Int |
Current traffic information. |
| vertexes | Double[] |
One-dimensional array that includes X and Y coordinates. (Example: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385]) |
Guide: Directions for driving
| Name | Type | Description |
|---|---|---|
| name | String |
Name of guidance. |
| x | Double |
X coordinate (longitude). |
| y | Double |
Y coordinate (latitude). |
| distance | Int |
Distance from the previous guidance point to the current guidance point in meters. |
| duration | Int |
Required time from the previous guidance point to the current guidance point in seconds. |
| type | Int |
Guidance type. |
| guidance | String |
Guidance message. |
| road_index | Int |
Index of the corresponding guidance. |
Sample
Request
curl -v -G 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
}
]
}
]
}
]
}
Directions via multiple waypoints
Basic information
| Method | URL | Authorization |
|---|---|---|
POST |
https://apis-navi.kakaomobility.com/v1/waypoints/directions |
REST API key |
| Permission | Prerequisite | Kakao Login | User consent |
|---|---|---|---|
| - | - | - | - |
This API provides route data from an origin to a destination via multiple waypoints. You can add up to 30 waypoints while the Directions for driving API allows up to five waypoints.
Add your REST API key to the request header, and send a POST request. You must set Content-Type to application/json in the request, and specify the request parameters.
If your request is successful, the API returns route data via a series of waypoints in JSON format. The response is the same as the response of Directions for driving. If failed, see Response code and error code to check its failure cause.
Request
Header
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_KEY}REST API key as a type of user authentication. |
O |
Body
| Name | Type | Description | Required |
|---|---|---|---|
| origin | Origin |
Departure point. | O |
| destination | Destination |
Arrival point. | O |
| waypoints | Waypoint[] |
Stop point along the route. Up to 30 waypoints are allowed. | X |
| priority | String |
Set priority options for navigation. Use one of the followings: - RECOMMEND: Recommended route.- TIME: Fastest route.- DISTANCE: Shortest route.(Default: RECOMMEND) |
X |
| avoid | String[] |
Set limitation options for navigation. Use one or more among the followings in array: - roadevent: Exclude routes with traffic congestion due to accidents, events, disasters, or roadworks.- ferries: Exclude sea route.- toll: Exclude toll road.- motorway: Exclude motorway.- schoolzone: Exclude school zone. (Example: ["roadevent", "motorway"])(Default: null) |
X |
| alternatives | Boolean |
Whether to provide alternative routes. - true: Provided. - false: Not provided. (Default: false) |
X |
| road_details | Boolean |
Whether to provide detailed road information. - true: Provided. - false: Not provided.(Default: false) |
X |
| car_type | Int |
Car type (Default: 1) |
X |
| car_fuel | String |
Fuel type. Use one of the followings: - GASOLINE: Gasoline - DIESEL: Diesel - LPG: LPG(Default: GASOLINE) |
X |
| car_hipass | Boolean |
Whether or not the Hi-pass system is used. - true: Using.- false: Not using.(Default: false) |
X |
| summary | Boolean |
Whether to provide summary for the routes. - true: Provided. - false: Not provided.(Default: false) |
X |
Origin: Directions via multiple waypoints
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
Origin name. | X |
| x | Double |
X coordinate (longitude). | O |
| y | Double |
Y coordinate (latitude). | O |
Destination: Directions via multiple waypoints
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
Destination name. | X |
| x | Double |
X coordinate (longitude). | O |
| y | Double |
Y coordinate (latitude). | O |
Waypoint: Directions via multiple waypoints
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
Waypoint name. | X |
| x | Double |
X coordinate (longitude). | O |
| y | Double |
Y coordinate (latitude). | O |
Response
The response is the same as the response of Directions for driving.
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
}
]
}
]
}
]
}
Directions from multiple origins
Basic information
| Method | URL | Authorization |
|---|---|---|
POST |
https://apis-navi.kakaomobility.com/v1/origins/directions |
REST API key |
| Permission | Prerequisite | Kakao Login | User consent |
|---|---|---|---|
| - | - | - | - |
This API provides route data from one or more origins to a destination. Because this API only provides summary for the routes, you must call the Directions for driving API to get detailed routes.
You can set up to 30 origins. If you need to set more than 30 origins, ask for a partnership via partnership@kakaomobility.com.
Add your REST API key to the request header, and send a POST request. You must set Content-Type to application/json in the request, and specify the request parameters.
If your request is successful, the API returns summary for the routes from the specified multiple origins to the specified destination in JSON format. If failed, see Response code and error code to check its failure cause.
Request
Header
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_KEY}REST API key as a type of user authentication. |
O |
Body
| Name | Type | Description | Required |
|---|---|---|---|
| origins | Origin[] |
Departure point. Up to 30 origins are allowed. | O |
| destination | Destination |
Arrival point. | O |
| radius | Int |
Radius to find routes in meters. (Maximum: 10000) |
O |
| priority | String |
Set priority options for navigation. Use one of the followings: - TIME: Fastest route.- DISTANCE: Shortest route.(Default: TIME) |
X |
| avoid | String[] |
Set limitation options for navigation. Use one or more among the followings in array: - roadevent: Exclude routes with traffic congestion due to accidents, events, disasters, or roadworks.- ferries: Exclude sea route.- toll: Exclude toll road.- motorway: Exclude motorway.- schoolzone: Exclude school zone. (Example: ["roadevent", "motorway"])(Default: null) |
X |
Origin: Directions from multiple origins
| Name | Type | Description | Required |
|---|---|---|---|
| key | String |
Random number to identify each origin. | O |
| x | Double |
X coordinate (longitude). | O |
| y | Double |
Y coordinate (latitude). | O |
Destination: Directions from multiple origins
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
Destination name. | X |
| x | Double |
X coordinate (longitude). | O |
| y | Double |
Y coordinate (latitude). | O |
Response
| Name | Type | Description |
|---|---|---|
| trans_id | String |
Unique identifier of a direction request. |
| routes | Route[] |
Route data. Array includes route data as many as the number of routes. |
Route: Directions from multiple origins
| Name | Type | Description |
|---|---|---|
| result_code | Int |
Result code of directions search. |
| result_msg | String |
Result message of directions search. |
| key | String |
The value of key specified for origins. |
| summary | Summary |
Summary information of directions. |
Summary: Directions from multiple origins
| Name | Type | Description |
|---|---|---|
| distance | Int |
Total distance in meters. |
| duration | Int |
Travel time to the destination in seconds. |
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
}
}
]
}
Directions to multiple destinations
Basic information
| Method | URL | Authorization |
|---|---|---|
POST |
https://apis-navi.kakaomobility.com/v1/destinations/directions |
REST API key |
| Permission | Prerequisite | Kakao Login | User consent |
|---|---|---|---|
| - | - | - | - |
This API provides route data from an origin to one or more destinations. Because this API only provides summary for the routes, you must call the Directions for driving API to get detailed routes.
You can set up to 30 destinations. If you need to set more than 30 destinations, ask for a partnership via partnership@kakaomobility.com.
Add your REST API key to the request header, and send a POST request. You must set Content-Type to application/json in the request, and specify the request parameters.
If your request is successful, the API returns summary for the routes from the specified origin to multiple destinations in JSON format. If failed, see Response code and error code to check its failure cause.
Request
Header
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_KEY}REST API key as a type of user authentication. |
O |
Body
| Name | Type | Description | Required |
|---|---|---|---|
| origin | Origin |
Departure point. | O |
| destinations | Destination[] |
Arrival point. Up to 30 destinations are allowed. | O |
| radius | Int |
Radius to find routes in meters. (Maximum: 10000) |
O |
| priority | String |
Set priority options for navigation. Use one of the followings: - TIME: Fastest route.- DISTANCE: Shortest route.(Default: TIME) |
X |
| avoid | String[] |
Set limitation options for navigation. Use one or more among the followings in array: - roadevent: Exclude routes with traffic congestion due to accidents, events, disasters, or roadworks.- ferries: Exclude sea route.- toll: Exclude toll road.- motorway: Exclude motorway.- schoolzone: Exclude school zone. (Example: ["roadevent", "motorway"])(Default: null) |
X |
Origin: Directions to multiple destinations
| Name | Type | Description | Required |
|---|---|---|---|
| name | String |
Origin name. | X |
| x | Double |
X coordinate (longitude). | O |
| y | Double |
Y coordinate (latitude). | O |
Destination: Directions to multiple destinations
| Name | Type | Description | Required |
|---|---|---|---|
| key | String |
Random number to identify each destination. | O |
| x | Double |
X coordinate (longitude). | O |
| y | Double |
Y coordinate (latitude). | O |
Response
Body
| Name | Type | Description |
|---|---|---|
| trans_id | String |
Unique identifier of a direction request. |
| routes | Route[] |
Route data. Array includes route data as many as the number of routes. |
Route: Directions to multiple destinations
| Name | Type | Description |
|---|---|---|
| result_code | Int |
Result code of directions search. |
| result_msg | String |
Result message of directions search. |
| key | String |
The value of key specified for destinations. |
| summary | Summary |
Summary information of directions. |
Summary: Directions to multiple destinations
| Name | Type | Description |
|---|---|---|
| distance | Int |
Total distance in meters. |
| duration | Int |
Travel time to the destination in seconds. |
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
}
}
]
}
Future driving estimation
Basic information
| Method | URL | Authorization |
|---|---|---|
GET |
https://apis-navi.kakaomobility.com/v1/future/directions |
REST API key |
| Permission | Prerequisite | Kakao Login | User consent |
|---|---|---|---|
| - | - | - | - |
This API provides route data from an origin to a destination at a specific time in the future. You must set departure_time to some time in the future.
Add your REST API key to the request header, and send a GET request. You can set waypoints, navigation options or vehicle information in the same as Directions for driving. If your request is successful, the API returns route data in JSON format. The data includes the estimated routes to the specified destination at the specified departure time. If failed, see Response code and error code to check its failure cause.
Request
Header
| Name | Description | Required |
|---|---|---|
| Authorization | Authorization: KakaoAK ${REST_API_KEY}REST API key as a type of user authentication. |
O |
Query parameter
| Name | Type | Description | Required |
|---|---|---|---|
| departure_time | String |
Departure time. Set some time in the future in YYYYMMDDHHMM format. (Example: 202507171010) |
O |
| origin | String |
Departure point. Use either format: - {X coordinate},{Y coordinate},name={origin name}- {X coordinate},{Y coordinate} (Example: "127.111202,37.394912,name=판교역" or "127.111202,37.394912") |
O |
| destination | String |
Arrival point. Use either format: - {X coordinate},{Y coordinate},name={destination name}- {X coordinate},{Y coordinate} (Example: "127.111202,37.394912,name=판교역" or "127.111202,37.394912") |
O |
| waypoints | String |
Stop point along the route. Up to 5 waypoints are allowed. For multiple waypoints, add | (or URL encoded character %7C) as many as the number of waypoints in either format:- {X coordinate},{Y coordinate},name={waypoint name} - {X coordinate},{Y coordinate} |
X |
| priority | String |
Set priority options for navigation. Use one of the followings: - RECOMMEND: Recommended route.- TIME: Fastest route.- DISTANCE: Shortest route.(Default: RECOMMEND) |
X |
| avoid | String |
Set limitation options for navigation. Use one or more among the followings: - roadevent: Exclude routes with traffic congestion due to accidents, events, disasters, or roadworks.- ferries: Exclude sea route.- toll: Exclude toll road.- motorway: Exclude motorway.- schoolzone: Exclude school zone.(Default: null)For multiple options, add | (or URL encoded character %7C) between options.(Example: avoid=roadevent|ferries) |
X |
| alternatives | Boolean |
Whether to provide alternative routes. - true: Provided. - false: Not provided. (Default: false) |
X |
| road_details | Boolean |
Whether to provide detailed road information. - true: Provided. - false: Not provided.(Default: false) |
X |
| car_type | Int |
Car type (Default: 1) |
X |
| car_fuel | String |
Fuel type. Use one of the followings: - GASOLINE: Gasoline - DIESEL: Diesel - LPG: LPG(Default: GASOLINE) |
X |
| car_hipass | Boolean |
Whether or not the Hi-pass system is used. - true: Using.- false: Not using.(Default: false) |
X |
| summary | Boolean |
Whether to provide summary for the routes. - true: Provided. - false: Not provided.(Default: false) |
X |
Response
The response is the same as the response of Directions for driving.
Sample
Request
curl -v -G 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
}
]
}
]
}
]
}
Reference
This chapter shows the common classes used in the Directions API.
result_code: Result code of directions search
| Code | Description |
|---|---|
| 0 | Succeed in getting directions. |
| 1 | Cannot get any direction. |
| 101 | Cannot find any road near the waypoints. |
| 102 | Cannot find any road near the origin. |
| 103 | Cannot find any road near the destination. |
| 104 | The origin and destination are set to the same location. |
| 105 | Traffic road event occurs around the origin. |
| 106 | Traffic road event occurs around the destination. |
| 107 | Traffic road event occurs around the waypoint. The order of waypoints is displayed in result_message, and it starts from the number one. |
| 201 | Multiple origins: Origin is not included in the geo-bounding box. |
| 202 | Multiple origins: Failed to find a direction due to exceeding the maximum number of origins. |
| 203 | Multiple origins: Failed to select the road set as destination. |
| 204 | Multiple origins: Exceeded Time limit for search directions. |
| 205 | Multiple origins: The origin is not allowed to pass due to road events. |
| 206 | Multiple origins: The destination is not allowed to pass due to road events. |
| 207 | Multiple origins: One or more origins are outside of the set radius. |
| 301 | Multiple destinations: Failed to select a road near the origin. |
| 302 | Multiple destinations: Failed to select a road near the destination. |
| 303 | Multiple destinations: Failed to find a direction due to exceeding the maximum number of destinations. |
| 304 | Multiple destinations: One or more destinations are outside of the set radius. |
traffic_state: Current traffic information
| Code | Description |
|---|---|
| 0 | No traffic information. |
| 1 | Traffic congestion. |
| 2 | Traffic delay. |
| 3 | Slow traffic. |
| 4 | Smooth traffic. |
| 6 | Road is closed due to traffic accident. |
car_type: Car type
| Code | Description |
|---|---|
| 1 | Passenger car, small-size van or truck (Example: Van for 16 passengers or less, 2.5 ton truck or less) Classification criteria: Vehicle with two axes, with a wheelbase of 279.4 mm or less |
| 2 | Mid-size van or truck (Example: Van for 17 to 32 passengers, 2.5 to 5.5 ton truck) Classification criteria: Vehicle with two axes, with a wheelbase of more than 279.4 mm, with a tread of 1,800 mm or less |
| 3 | Large-size van or truck (Example: Van for 33 passengers or more, 5.5 to 10 ton truck) Classification criteria: Vehicle with two axes, with a wheelbase of more than 279.4 mm, with a tread of more than 1,800 mm |
| 4 | Large truck (Example: 10 to 20 ton truck) Classification criteria: Vehicle with three axes |
| 5 | Special truck (Example: 20 ton truck or more) Classification criteria: Vehicle with four or more axes |
| 6 | Compact car Classification criteria: Vehicle with engine displacement of less than 1,000cc or with a dimension of less than 3.6 x 1.6 x 2.0 m (length x width x height) |
| 7 | Motorcycle |
type: Guidance type
| Code | Description |
|---|---|
| 0 | Go straight ahead |
| 1 | Turn left |
| 2 | Turn right |
| 3 | Make a U-turn |
| 5 | To the left |
| 6 | To the right |
| 7 | Expressway exit |
| 8 | Expressway exit on your left |
| 9 | Expressway exit on your right |
| 10 | Expressway entrance |
| 11 | Expressway entrance on your left |
| 12 | Expressway entrance on your right |
| 14 | Approaching overpass |
| 15 | Approaching underpass |
| 16 | Beside overpass |
| 17 | Beside underpass |
| 18 | To the right at your 1 o'clock |
| 19 | To the right at your 2 o'clock |
| 20 | To the right at your 3 o'clock |
| 21 | To the right at your 4 o'clock |
| 22 | To the right at your 5 o'clock |
| 23 | At your at 6 o'clock |
| 24 | To the left at your 7 o'clock |
| 25 | To the left at your 8 o'clock |
| 26 | To the left at your 9 o'clock |
| 27 | To the left at your 10 o'clock |
| 28 | To the left at your 11 o'clock |
| 29 | At your 12 o'clock |
| 30 | To the right at your 1 o'clock at the roundabout |
| 31 | To the right at your 2 o'clock at the roundabout |
| 32 | To the right at your 3 o'clock at the roundabout |
| 33 | To the right at your 4 o'clock at the roundabout |
| 34 | To the right at your 5 o'clock at the roundabout |
| 35 | To your 6 o'clock at the roundabout |
| 36 | To the left at your 7 o'clock at the roundabout |
| 37 | To the left at your 8 o'clock at the roundabout |
| 38 | To the left at your 9 o'clock at the roundabout |
| 39 | To the left at your 10 o'clock at the roundabout |
| 40 | To the left at your 11 o'clock at the roundabout |
| 41 | To your 12 o'clock at the roundabout |
| 42 | Expressway exit |
| 43 | Expressway exit on your left |
| 44 | Expressway exit on your right. |
| 45 | Expressway entrance |
| 46 | Expressway entrance on your left. |
| 47 | Expressway entrance on your right |
| 48 | Expressway entrance on your left. |
| 49 | Expressway entrance on your right |
| 61 | Approaching ferry route |
| 62 | Exit ferry route |
| 70 | To the right at your 1 o'clock at the roundabout |
| 71 | To the right at your 2 o'clock at the roundabout |
| 72 | To the right at your 3 o'clock at the roundabout |
| 73 | To the right at your 4 o'clock at the roundabout |
| 74 | To the right at your 5 o'clock at the roundabout |
| 75 | 6 o'clock at the roundabout |
| 76 | To the left at your 7 o'clock at the roundabout |
| 77 | To the left at your 8 o'clock at the roundabout |
| 78 | To the left at your 9 o'clock at the roundabout |
| 79 | To the left at your 10 o'clock at the roundabout |
| 80 | To the left at your 11 o'clock at the roundabout |
| 81 | 12 o'clock at the roundabout |
| 82 | Go straight to the right |
| 83 | Go straight to the left |
| 84 | Approaching tollgate |
| 85 | Approaching one-tolling zone |
| 86 | Joining a merging lane after diverging |
| 100 | Origin |
| 101 | Destination |
| 1000 | Waypoint |
| 300 | Tollgate |
| 301 | Service area |