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
GET	https://apis-navi.kakaomobility.com/v1/future/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

curl -v -X GET "https://apis-navi.kakaomobility.com/v1/future/directions?origin=127.11015314141542,37.39472714688412,angle=270&destination=127.10824367964793,37.401937080111644&departure_time=202109170000" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" // The REST API key issued from Kakao Developers

The request parameters are as follows:

Table 3 Request parameters

Name	Type	Description	Required
departure_time	String	Departure time. Set a time after the current time in YYYYMMDDHHMM format. (Example: 202107171010)	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	Waypoints. Up to 5 waypoints are allowed. The total route distance, including all waypoints, must be less than 1,500 km. For each waypoint, enter ${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	Priority option for route search Use one of the following: RECOMMEND: The recommended route TIME: The fastest route DISTANCE: The shortest route (Default: RECOMMEND)	Optional
avoid	String	Restriction options for route search The following values are available: ferries: Ferry routes toll: Toll roads motorway: Motorways schoolzone: School zones uturn: 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 lane closures (entire road closures) 1: Do not reflect full lane closures near the origin and destination 2: Do not reflect full lane closures on any section (Default: 0)	Optional
alternatives	Boolean	Whether to provide alternative routes true: Provide alternative routes false: Do not provide alternative routes (Default: false)	Optional
road_details	Boolean	Whether to provide detailed road information true: Provide detailed road information false: 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: Gasoline DIESEL: Diesel LPG: LPG (Default: GASOLINE)	Optional
car_hipass	Boolean	Whether the vehicle is equipped with Hi-pass (Electronic Toll Collection) true: Equipped with Hi-pass false: Not equipped with Hi-pass (Default: false)	Optional
summary	Boolean	Sets the response scope of route information. 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 success, the success status of the request is delivered via the HTTP status code, and the response body is delivered in JSON format.

Sample Response

{
  "trans_id": "0194de169a8d79c98f718af8c8410932",
  "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.10873060789754,
                  "min_y": 37.39446252338457,
                  "max_x": 127.1098222529551,
                  "max_y": 37.40242724407785
              },
              "fare": {
                  "taxi": 5100,
                  "toll": 0
              },
              "distance": 1012,
              "duration": 304
          },
          "sections": [
              {
                  "distance": 1012,
                  "duration": 304,
                  "bound": {
                      "min_x": 127.10863660151416,
                      "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": 224,
                          "traffic_speed": 11.0,
                          "traffic_state": 2,
                          "vertexes": [
                              127.10966790676201,
                              37.394469584427156,
                              127.10967141980313,
                              37.39512739646385,
                              127.10968100356395,
                              37.396226781360426,
                              127.10967417816033,
                              37.39775855885587,
                              127.10968323318781,
                              37.39794785293074,
                              127.10967534594126,
                              37.39861458950405,
                              127.10967214334856,
                              37.399840028043634,
                              127.1096931266438,
                              37.40093048716485,
                              127.10967543155922,
                              37.40242613861426
                          ]
                      },
                      {
                          "name": "판교역로241번길",
                          "distance": 92,
                          "duration": 72,
                          "traffic_speed": 12.0,
                          "traffic_state": 2,
                          "vertexes": [
                              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.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": 224,
                          "type": 1,
                          "guidance": "좌회전",
                          "road_index": 2
                      },
                      {
                          "name": "",
                          "x": 127.10863660151416,
                          "y": 37.40240029023456,
                          "distance": 92,
                          "duration": 72,
                          "type": 1,
                          "guidance": "좌회전",
                          "road_index": 3
                      },
                      {
                          "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 objects

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 exist, {number of waypoints + 1} sections (route segments) are created. (Example: If the number of waypoints is 2, a total of 3 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 consisting 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