Request
This section describes the request method and the required request headers. If the request fails, see Troubleshooting for detailed error information.
Request Method
Table 1 Request Method
| Method | URL |
|---|---|
GET | https://apis-navi.kakaomobility.com/v1/directions |
Request Headers
Table 2 Request Headers
| Parameter | Description |
|---|---|
| Authorization | KakaoAK ${REST_API_KEY} {REST_API_KEY}: The REST API key issued from Kakao Developers |
| Content-Type | application/json |
Sample Request
bash
curl -v -X GET "https://apis-navi.kakaomobility.com/v1/directions?origin=127.10764191124568,37.402464820205246,angle=270&destination=127.11056336672839,37.39419693653072&summary=false&waypoints=127.17354989857544,37.36629687436494&priority=RECOMMEND&car_fuel=GASOLINE&car_hipass=false&alternatives=false&road_details=false" \
-H "Authorization: KakaoAK ${REST_API_KEY}" // The REST API key issued from Kakao DevelopersThe request parameters are as follows:
Table 3 Request Parameters
| Name | Type | Description | Required |
|---|---|---|---|
origin | String | Origin Use one of the following formats: 1. ${X coordinate},${Y coordinate},name=${origin name} (Example: " 127.111202,37.394912,name=판교역") 2. ${X coordinate},${Y coordinate} (Example: " 127.111202,37.394912") 3. ${X coordinate},${Y coordinate},${angle}(Example:" 127.111202,37.394912,angle=90")angle: Specifies the initial travel direction at the origin. Enter an integer within the range of 0 to 360.(Directions based on angle: 0 = North, 90 = East, 180 = South, 270 = West, applied clockwise. Values outside this range are ignored.) | Required |
destination | String | Destination Use one of the following formats: ${X coordinate},${Y coordinate},name=${destination name} or ${X coordinate},${Y coordinate}(Example: " 127.111202,37.394912,name=판교역" or "127.111202,37.394912") | Required |
waypoints | String | Stop point along the route. Up to 5 waypoints are allowed. The total route distance, including all waypoints, must be less than 1,500 km. Enter as many entries as the number of waypoints in the format ${X coordinate},${Y coordinate},name=${waypoint name} or ${X coordinate},${Y coordinate}, separated by | (or the URL encoded character %7C).(Example: " 127.111202,37.394912,name=판교역 | 127.112275,37.392815") | Optional |
priority | String | Set priority options for route search. Use one of the following: RECOMMEND: The recommended routeTIME: The fastest routeDISTANCE: The shortest route(Default: RECOMMEND) | Optional |
avoid | String | Set limitation options for route search. Use one or more of the following: ferries: Exclude sea routetoll: Exclude toll roadmotorway: Exclude motorwayschoolzone: Exclude school zoneuturn: Exclude U-turns(Default: null)To use multiple restriction options, separate them with | (or the URL encoded character %7C).(Example: avoid=motorway|ferries) | Optional |
roadevent | Int | Option to reflect road closure information caused by traffic incidents (traffic obstructions such as accidents, events, disasters, or road construction)0: Reflect full road closures (entire road blocked)1: Do not reflect full road closures near the origin and destination2: Do not reflect any full road closures in any section(Default: 0) | Optional |
alternatives | Boolean | Whether to provide alternative routestrue: Providedfalse: Not provided(Default: false) | Optional |
road_details | Boolean | Whether to provide detailed road informationtrue: Providedfalse: Not provided(Default: false) | Optional |
car_type | Int | Car type (Default: 1) | Optional |
car_fuel | String | Fuel type Use one of the following: GASOLINE: GasolineDIESEL: DieselLPG: LPG(Default: GASOLINE) | Optional |
car_hipass | Boolean | Whether or not the Hi-pass system (Electronic Toll Collection) is usedtrue: In usefalse: Not in use(Default: false) | Optional |
summary | Boolean | Determines whether the response includes only the route summary or both the summary and detailed route information.true: Returns summary information only (excludes bound, roads, and guides in sections).false: Returns summary information together with detailed route information (includes bound, roads, and guides in sections).(Default: false) | Optional |
Response
Upon successful response, the success status is delivered via HTTP status code, and the response body is delivered in JSON format.
Sample Response
bash
{
"trans_id": "01948280a50d700d945a8ec5c132709d",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공", // "Directions successful"
"summary": {
"origin": {
"name": "",
"x": 127.10763058573032,
"y": 37.40246478787756
},
"destination": {
"name": "",
"x": 127.1098265381582,
"y": 37.394425724914576
},
"waypoints": [
{
"name": "",
"x": 127.17353858063272,
"y": 37.3662968484953
}
],
"priority": "RECOMMEND",
"bound": {
"min_x": 127.10699672876241,
"min_y": 37.35782058991495,
"max_x": 127.17437025337696,
"max_y": 37.40371556711698
},
"fare": {
"taxi": 22200,
"toll": 0
},
"distance": 19032,
"duration": 3494
},
"sections": [
{
"distance": 10035,
"duration": 1880,
"bound": {
"min_x": 127.16765984810529,
"min_y": 37.35821336047281,
"max_x": 127.17352998262038,
"max_y": 37.40325103149278
},
"roads": [
{
"name": "판교역로241번길", // "Pangyoyeok-ro 241beon-gil"
"distance": 186,
"duration": 47,
"traffic_speed": 14.0,
"traffic_state": 2,
"vertexes": [
127.10763122680424,
37.40241072822385,
// Code omitted
127.10645821495126,
37.40322184743522
]
},
...
{
"name": "문형산길", // "Munhyeongsan-gil"
"distance": 596,
"duration": 104,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.16765984810529,
37.36601233289304,
// Code omitted
127.17352998262038,
37.36708073181059
]
}
],
"guides": [
{
"name": "출발지", // "Origin"
"x": 127.10763122680424,
"y": 37.40241072822385,
"distance": 0,
"duration": 0,
"type": 100,
"guidance": "출발지", // "Origin"
"road_index": 0
},
// Code omitted
{
"name": "경유지", // "Waypoint"
"x": 127.17352998262038,
"y": 37.36708073181059,
"distance": 596,
"duration": 104,
"type": 1000,
"guidance": "경유지", // "Waypoint"
"road_index": -1
}
]
},
{
"distance": 8997,
"duration": 1614,
"bound": {
"min_x": 127.10966790676201,
"min_y": 37.35832776837687,
"max_x": 127.17475981481635,
"max_y": 37.39447077471427
},
"roads": [
{
"name": "문형산안길1번길", // "Munhyeongsanan-gil 1beon-gil"
"distance": 85,
"duration": 19,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.17352998262038,
37.36708073181059,
127.17357513799075,
37.36708104732421,
127.17372149772216,
37.367118113235804,
127.1739231164781,
37.36726369503417,
127.17434992149448,
37.36746491368941
]
},
// Code omitted
{
"name": "",
"distance": 14,
"duration": 3,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10982600539788,
37.39447077471427
]
}
],
"guides": [
{
"name": "경유지", // "Waypoint"
"x": 127.17352998262038,
"y": 37.36708073181059,
"distance": 0,
"duration": 0,
"type": 1000,
"guidance": "경유지", // "Waypoint"
"road_index": 0
},
// Code omitted
{
"name": "",
"x": 127.10966790676201,
"y": 37.394469584427156,
"distance": 81,
"duration": 50,
"type": 2,
"guidance": "우회전", // "Turn right"
"road_index": 11
},
{
"name": "목적지", // "Destination"
"x": 127.10982600539788,
"y": 37.39447077471427,
"distance": 14,
"duration": 3,
"type": 101,
"guidance": "목적지", // "Destination"
"road_index": -1
}
]
}
]
}
]
}The response object information is as follows:
Table 4 Response Object
| Name | Type | Description | Required |
|---|---|---|---|
trans_id | String | Unique identifier of a route request | Required |
routes | Object[] | Route information When the alternatives parameter is set to true, one or more routes may be provided. | Required |
result_code | Int | Route search result code | Required |
result_msg | String | Route search result message | Required |
summary | Object | Route summary information | Required |
origin | Object | Origin information | Required |
name | String | Origin name | Required |
x | Double | X coordinate (longitude) | Required |
y | Double | Y coordinate (latitude) | Required |
destination | Object | Destination information | Required |
name | String | Destination name | Required |
x | Double | X coordinate (longitude) | Required |
y | Double | Y coordinate (latitude) | Required |
waypoints | Object[] | Waypoint information | Required |
name | String | Waypoint name | Required |
x | Double | X coordinate (longitude) | Required |
y | Double | Y coordinate (latitude) | Required |
priority | String | Priority option for route search | Required |
bound | Object | Rectangular bounding box that includes all routes | Optional |
min_x | Double | X coordinate of the bottom left corner of the bounding box | Required |
min_y | Double | Y coordinate of the bottom left corner of the bounding box | Required |
max_x | Double | X coordinate of the top right corner of the bounding box | Required |
max_y | Double | Y coordinate of the top right corner of the bounding box | Required |
fare | Object | Fare information | Required |
taxi | Int | Taxi fare in South Korean won (KRW) | Required |
toll | Int | Toll fare in South Korean won (KRW) | Required |
distance | Int | Total distance of the search result in meters | Required |
duration | Int | Time required to reach the destination in seconds | Required |
sections | Object[] | 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) | Required |
distance | Int | Section distance in meters | Required |
duration | Int | Total travel time of the search result in seconds | Required |
bound | Object | Rectangular bounding box that includes all routes Only returned if summary is set to false. | Optional |
min_x | Double | X coordinate of the bottom left corner of the bounding box | Required |
min_y | Double | Y coordinate of the bottom left corner of the bounding box | Required |
max_x | Double | X coordinate of the top right corner of the bounding box | Required |
max_y | Double | Y coordinate of the top right corner of the bounding box | Required |
roads | Object[] | Road information Only returned if summary is set to false. | Optional |
name | String | Road name | Required |
distance | Int | Road length in meters | Required |
duration | Int | Estimated travel time in seconds Currently, the estimated travel time and the actual travel time are set to the same value. | Required |
traffic_speed | Double | Current traffic speed in km/h | Required |
traffic_state | Int | Current traffic state | Required |
vertexes | Double[] | One-dimensional array that consists of X and Y coordinates (Example: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] ) | Required |
guides | Object[] | Guidance information Only returned if summary is set to false. | Optional |
name | String | Name | Required |
x | Double | X coordinate (longitude) | Required |
y | Double | Y coordinate (latitude) | Required |
distance | Int | Distance from the previous guidance point to the current guidance point in meters | Required |
duration | Int | Time from the previous guidance point to the current guidance point in seconds | Required |
type | Int | Guidance type | Required |
guidance | String | Guidance message | Required |
road_index | Int | Link index for the current guidance | Required |