Request
This section describes the request method and the contents of each request header. If the request fails, see Troubleshooting for detailed error information.
Request Method
Table 1 Request Method
| Method | URL |
|---|---|
POST | https://apis-navi.kakaomobility.com/v1/waypoints/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 POST "https://apis-navi.kakaomobility.com/v1/waypoints/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \ // The REST API key issued from Kakao Developers
-d '{
"origin": {
"x": "127.11024293202674",
"y": " 37.394348634049784",
"angle": 270
},
"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,
"summary": false
}'The request parameters are as follows:
Table 3 Request Parameters
| Name | Type | Description | Required |
|---|---|---|---|
origin | Object | Origin | Required |
name | String | Origin name | Optional |
x | Double | X coordinate (longitude) | Required |
y | Double | Y coordinate (latitude) | Required |
angle | Int | 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.) | Optional |
destination | Object | Destination | Required |
name | String | Destination name | Optional |
x | Double | X coordinate (longitude) | Required |
y | Double | Y coordinate (latitude) | Required |
waypoints | Object[] | Waypoints. Up to 30 waypoints are allowed. The total route distance, including all waypoints, must be less than 1,500 km. | Optional |
name | String | Waypoint name | Optional |
x | Double | X coordinate (longitude) | Required |
y | Double | Y coordinate (latitude) | Required |
priority | String | Priority option for route search Use one of the following: RECOMMEND: The recommended routeTIME: The fastest routeDISTANCE: The shortest route(Default: RECOMMEND) | Optional |
avoid | String[] | Restriction options for route search The following values are available: ferries: Ferry routestoll: Toll roadsmotorway: Motorwaysschoolzone: School zonesuturn: U-turns(Default: null)Use multiple restriction options by connecting them as follows: (Example: [" ferries", "motorway"]) | 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 lane closures (entire road closures)1: Do not reflect full lane closures near the origin and destination2: Do not reflect full lane closures in any section(Default: 0) | Optional |
alternatives | Boolean | Whether to provide alternative routestrue: Provide alternative routesfalse: Do not provide alternative routes(Default: false) | Optional |
road_details | Boolean | Whether to provide detailed road informationtrue: Provide detailed road informationfalse: Do not provide detailed road information(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 the Hi-pass system (electronic toll collection) is installedtrue: Hi-pass installedfalse: Hi-pass not installed(Default: false) | Optional |
summary | Boolean | Sets the scope of the route information response.true: Returns summary information only (excludes bound, roads, and guides in sections)false: Returns summary information together with detailed information (includes bound, roads, and guides in sections)(Default: false) | Optional |
Response
Upon a successful response, the success status is delivered via an HTTP status code, and the response body is delivered in JSON format.
Sample response
bash
{
"trans_id": "0194de353ee97a56a7807b8a505eb4da",
"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.10873060789754,
"min_y": 37.39446252338457,
"max_x": 127.11400101911747,
"max_y": 37.402458630852735
},
"fare": {
"taxi": 6600,
"toll": 0
},
"distance": 2193,
"duration": 574
},
"sections": [
{
"distance": 1074,
"duration": 280,
"bound": {
"min_x": 127.11341931516797,
"min_y": 37.394469584427156,
"max_x": 127.11406301821938,
"max_y": 37.398332068681995
},
"roads": [
{
"name": "",
"distance": 22,
"duration": 5,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10991634747967,
37.39447145478345,
127.10966790676201,
37.394469584427156
]
},
{
"name": "판교역로",
"distance": 364,
"duration": 97,
"traffic_speed": 27.0,
"traffic_state": 3,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10967141980313,
37.39512739646385,
127.10968100356395,
37.396226781360426,
127.10967417816033,
37.39775855885587
]
},
{
"name": "판교역로192번길",
"distance": 398,
"duration": 113,
"traffic_speed": 23.0,
"traffic_state": 3,
"vertexes": [
127.10967417816033,
37.39775855885587,
127.10991144303469,
37.39775133437272,
127.11030660039278,
37.39776331905757,
127.11058861237368,
37.39779247292587,
127.11190492731849,
37.39822587238842,
127.11217511696259,
37.39829998747621,
127.11242335797999,
37.39831987264784,
127.11275097123547,
37.39831332063064,
127.1130784782746,
37.3983157776669,
127.11404960021814,
37.398332068681995
]
},
{
"name": "",
"distance": 233,
"duration": 39,
"traffic_speed": 42.0,
"traffic_state": 0,
"vertexes": [
127.11404960021814,
37.398332068681995,
127.11403422576758,
37.39771922184463,
127.11406301821938,
37.39623266200683
]
},
{
"name": "대왕판교로606번길",
"distance": 57,
"duration": 26,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11406301821938,
37.39623266200683,
127.11341931516797,
37.39622783738649
]
}
],
"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.10967417816033,
"y": 37.39775855885587,
"distance": 364,
"duration": 97,
"type": 2,
"guidance": "광장로 방면으로 우회전",
"road_index": 2
},
{
"name": "",
"x": 127.11404960021814,
"y": 37.398332068681995,
"distance": 398,
"duration": 113,
"type": 2,
"guidance": "백현동 방면으로 우회전",
"road_index": 3
},
{
"name": "",
"x": 127.11406301821938,
"y": 37.39623266200683,
"distance": 233,
"duration": 39,
"type": 2,
"guidance": "판교테크노밸리 양재 내곡 방면으로 우회전",
"road_index": 4
},
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 57,
"duration": 26,
"type": 1000,
"guidance": "경유지",
"road_index": -1
}
]
},
{
"distance": 1119,
"duration": 294,
"bound": {
"min_x": 127.10863660151416,
"min_y": 37.39622538141045,
"max_x": 127.11341931516797,
"max_y": 37.40242613861426
},
"roads": [
{
"name": "대왕판교로606번길",
"distance": 29,
"duration": 6,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11341931516797,
37.39622783738649,
127.11309181718316,
37.39622538141045
]
},
{
"name": "분당내곡로",
"distance": 392,
"duration": 62,
"traffic_speed": 25.0,
"traffic_state": 3,
"vertexes": [
127.11309181718316,
37.39622538141045,
127.11307829458244,
37.39641450597087,
127.1130803894646,
37.398153598349445,
127.11307964622586,
37.39821666808455,
127.1130784782746,
37.3983157776669,
127.11308594924428,
37.39864022099831,
127.11311303420219,
37.39921711263319,
127.11313041857109,
37.39965877010523,
127.11312925062586,
37.399757879664605
]
},
{
"name": "대왕판교로644번길",
"distance": 124,
"duration": 50,
"traffic_speed": 20.0,
"traffic_state": 3,
"vertexes": [
127.11312925062586,
37.399757879664605,
127.11274420726458,
37.39984509856906,
127.11173886656147,
37.39985557194009
]
},
{
"name": "",
"distance": 559,
"duration": 173,
"traffic_speed": 13.0,
"traffic_state": 2,
"vertexes": [
127.11173886656147,
37.39985557194009,
127.11175987981302,
37.40094603107842,
127.11174254485269,
37.40241465350646,
127.11170855662199,
37.402423408918274,
127.10967543155922,
37.40242613861426,
127.10863660151416,
37.40240029023456
]
},
{
"name": "",
"distance": 15,
"duration": 3,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10863660151416,
37.40240029023456,
127.1086494963113,
37.402265226201656
]
}
],
"guides": [
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 0,
"duration": 0,
"type": 1000,
"guidance": "판교테크노밸리 양재 내곡 방면으로 경유지",
"road_index": 0
},
{
"name": "판교역사거리",
"x": 127.11309181718316,
"y": 37.39622538141045,
"distance": 29,
"duration": 6,
"type": 2,
"guidance": "동판교IC 내곡,서울 방면으로 우회전",
"road_index": 1
},
{
"name": "삼평사거리",
"x": 127.11312925062586,
"y": 37.399757879664605,
"distance": 392,
"duration": 62,
"type": 1,
"guidance": "대왕판교로 경기창조경제혁신센터 방면으로 좌회전",
"road_index": 2
},
{
"name": "",
"x": 127.11173886656147,
"y": 37.39985557194009,
"distance": 124,
"duration": 50,
"type": 2,
"guidance": "우회전",
"road_index": 3
},
{
"name": "",
"x": 127.10863660151416,
"y": 37.40240029023456,
"distance": 559,
"duration": 173,
"type": 1,
"guidance": "좌회전",
"road_index": 4
},
{
"name": "목적지",
"x": 127.1086494963113,
"y": 37.402265226201656,
"distance": 15,
"duration": 3,
"type": 101,
"guidance": "목적지",
"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 alternatives 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 information by section If waypoints are specified, as many sections (route segments) as {number of waypoints + 1} are created. (Example: If the number of waypoints is two, a total of three sections are created. section1: origin → waypoint 1 section2: waypoint 1 → waypoint 2 section3: waypoint 2 → 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 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 |