🌐 한국어

Future Driving Directions

This API provides route information from a single origin to a single destination at a specified time in the future. The departure time must be set to a time after the current time. You can add up to 5 waypoints, and the total route distance, including all waypoints, must be less than 1,500 km.

DANGER

A REST API key is required to use this API. Please refer to Getting Started for instructions on how to register an app and obtain a REST API key.

Request

This section describes the request method and the required request headers. If the request fails, see Troubleshooting for detailed error information.

Request Method

Method	URL
GET	https://apis-navi.kakaomobility.com/affiliate/v1/future/directions

Request Headers

Parameter	Description
Authorization	KakaoAK ${REST_API_KEY} {REST_API_KEY}: The API key issued from Kakao Developers
Content-Type	application/json

Sample request

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

The request parameters are as follows:

Parameters

Name	Type	Description	Required
departure_time	String	Departure time. Set some time in the future in YYYYMMDDHHMM format. (Example: 202107171010)	O
origin	String	Departure point 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 departure point. 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.)	O
destination	String	Arrival point Use one of the following formats: 1. ${X coordinate},${Y coordinate},name=${destination name} (Example: "127.111202,37.394912,name=판교역") 2. ${X coordinate},${Y coordinate} (Example: "127.111202,37.394912") 3.${X coordinate},${Y coordinate},${point_correction} (Example:"127.111202,37.394912, correction_point=parking") point_correction: Adjustment option for guide points near destinations. • none: No adjustment. (Equivalent to omitting the value or setting it to null.) • building_entrance: Building entrance • parking: Parking lot entrance (Default: null. If omitted, no adjustment is applied.)	O
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. To specify multiple waypoints, separate them with | (or URL encoded character %7C) using the following formats: 1. ${X coordinate},${Y coordinate},name=${waypoint name} 2. ${X coordinate},${Y coordinate} 3.${X coordinate},${Y coordinate},${point_correction} (예:"127.111202,37.394912,name=판교역| 127.112275,37.392815|127.111202,37.394912, correction_point=parking") point_correction: Adjustment option for guide points near waypoints. • none: No adjustment. (Equivalent to omitting the value or setting it to null.) • building_entrance: Building entrance • parking: Parking lot entrance (Default: null. If omitted, no adjustment is applied.)	X
priority	String	Set priority options for navigation. Use one of the following: RECOMMEND: The recommended route TIME: The fastest route DISTANCE: The shortest route MAIN_ROAD: Prioritizes main roads NO_TRAFFIC_INFO: The fastest route without considering real-time traffic information (Default: RECOMMEND)	X
avoid	String	Set limitation options for navigation. Use one or more of the following in the array: ferries: Exclude sea route toll: Exclude toll road motorway: Exclude motorway schoolzone: Exclude school zone uturn: Exclude U-turns (Default: null) To use multiple restriction options, separate them with |(or URL encoded character %7C). (Example: avoid=motorway|ferries)	X
roadevent	Int	Road Blockage Information Option Due to Incidents (e.g., traffic accidents, events, disasters, or road construction): 0: Reflect full road closures 1: Do not reflect full road closures near the origin and destination. 2: Do not reflect any full road closures. (Default: 0)	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
road_details_extra_info	String	Additional Detailed Road Information. Applied when the road_details option is true. • safety: Safe driving • roadevent: Incident information (Example: road_details_extra_info=safety or road_details_extra_info=safety|roadevent)	X
car_type	Int	Car type (Default: 1)	X
car_length	Int	Vehicle length in cm -1: No value	X
car_width	Int	Vehicle width in cm -1: No value	X
car_height	Int	Vehicle height in cm -1: No value	X
car_weight	Int	Weight in 0.1-ton units -1: No value	X
car_fuel	String	Fuel type Use one of the following: GASOLINE: Gasoline DIESEL: Diesel LPG: LPG (Default: GASOLINE)	X
car_hipass	Boolean	Whether or not the Hi-pass system (Electronic Toll Collection) is used true: In use false: Not in use (Default: false)	X
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)	X

Response

Upon successful response, the success status is delivered via HTTP status code, and the request body is delivered in JSON format.

Sample response

{
  "trans_id": "890c12877fc743138c40b3844c813eb9",
  "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": 297
          },
          "sections": [
              {
                  "distance": 1033,
                  "duration": 297,
                  "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,
                          "traffic_state": 0,
                          "vertexes": [
                              127.10991634747967,
                              37.39447145478345,
                              127.10966790676201,
                              37.394469584427156
                          ]
                      },
                      {
                          "name": "판교역로",
                          "distance": 883,
                          "duration": 224,
                          "traffic_speed": 12,
                          "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": 128,
                          "duration": 68,
                          "traffic_speed": 16,
                          "traffic_state": 2,
                          "vertexes": [
                              127.10967543155922,
                              37.40242613861426,
                              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": 224,
                          "type": 1,
                          "guidance": "좌회전",
                          "road_index": 2
                      },
                      {
                          "name": "목적지",
                          "x": 127.10824109988312,
                          "y": 37.402415329497174,
                          "distance": 128,
                          "duration": 68,
                          "type": 101,
                          "guidance": "목적지",
                          "road_index": -1
                      }
                  ]
              }
          ]
      }
  ]
}

The response object information is as follows:

Response object

Name	Type	Description	Required
trans_id	String	Unique identifier of a direction request	O
routes	Object[]	Route Information When the alternativesparameter is set to true, one or more routes may be provided.	O
result_code	Int	Result code	O
result_msg	String	Result message	O
summary	Object	Summary information of directions	O
origin	Object	Origin information	O
name	String	Origin name	O
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
destination	Object	Destination information	O
name	String	Destination name	O
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
correction_result	String	Information about guide points adjusted near the destination (If no option value for point_correctionis set, correction_resultis not included in the response.) • none: No adjustment • building_entrance: Building entrance • parking: Parking lot entrance	O
waypoints	Object[]	Waypoint information	O
name	String	Waypoint name	O
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
correction_result	String	Information about guide points adjusted near the Waypoint (If no option value for point_correctionis set, correction_resultis not included in the response.) • none: No adjustment • building_entrance: Building entrance • parking: Parking lot entrance	O
priority	String	Priority options for navigation	O
bound	Object	Geo-bounding box that includes all routes	X
min_x	Double	X coordinate of the bottom left corner of the geo-bounding box	O
min_y	Double	Y coordinate of the bottom left corner of the geo-bounding box	O
max_x	Double	X coordinate of the top right corner of the geo-bounding box	O
max_y	Double	Y coordinate of the top right corner of the geo-bounding box	O
fare	Object	Total fare	O
taxi	Int	Taxi fare in South Korean won (KRW)	O
toll	Int	Toll fare in South Korean won (KRW)	O
distance	Int	Distance between sections in meters	O
duration	Int	Total required time in seconds	O
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)	O
distance	Int	Distance between sections in meters	O
duration	Int	Total required time in seconds	O
bound	Object	Geo-bounding box that includes all routes Only returned if summary is set to false.	X
min_x	Double	X coordinate of the bottom left corner of the geo-bounding box	O
min_y	Double	Y coordinate of the bottom left corner of the geo-bounding box	O
max_x	Double	X coordinate of the top right corner of the geo-bounding box	O
max_y	Double	Y coordinate of the top right corner of the geo-bounding box	O
roads	Object[]	Road information Only returned if summary is set to false.	X
name	String	Road name	O
distance	Int	Road distance in meters	O
duration	Int	Estimated travel time in seconds, which is considered as the actual required time.	O
traffic_speed	Double	Current traffic speed in kilometers per hour.	O
traffic_state	Int	Current traffic information	O
vertexes	Double[]	One-dimensional array that includes X and Y coordinates (Example: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] )	O
guides	Object[]	Guidance information Only returned if summary is set to false.	X
name	String	Name of guidance	O
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
distance	Int	Distance from the previous guidance point to the current guidance point in meters	O
duration	Int	Required time from the previous guidance point to the current guidance point in seconds	O
type	Int	Guidance type	O
guidance	String	Guidance message	O
road_index	Int	Index of the corresponding guidance	O