페이지 이동경로
  • Docs>
  • Kakao Navi>
  • REST API

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

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
URL
GET /v1/directions HTTP/1.1
Host: apis-navi.kakaomobility.com
Authorization: KakaoAK ${REST_API_KEY}
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
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 -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
                        }
                    ]
                }
            ]
        }
    ]
}        

Directions via multiple waypoints

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
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 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

This API provides route data from one or more origins to a destination. Since 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
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[] 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

This API provides route data from an origin to one or more destinations. Since 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
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 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
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

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
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 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 -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
                        }
                    ]
                }
            ]
        }
    ]
}

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