🌐 한국어

Multi-Waypoint

This API provides detailed route information from a single origin to a single destination via multiple waypoints. You can add up to 100 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
POST	https://apis-navi.kakaomobility.com/affiliate/v1/waypoints/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 POST "http://navi-api.kakao.com/affliate/v1/waypoints/directions100" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \ // The API key issued from Kakao Developers
-d '{
  "origin": {
      "x": "127.11024293202674",
      "y": " 37.394348634049784"
  },
  "destination": {
      "x": "127.10860518470294",
      "y": "37.401999820065534"
  },
  "waypoints": [
      {
          "name": "name0",
          "x": 127.11341936045922,
          "y": 37.39639094915999
      }
  ]
}'

The request parameters are as follows:

Parameters

Name	Type	Description	Required
origin	Object	Departure point	O
name	String	Origin name	X
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
angle	Int	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.)	X
destination	Object	Arrival point	O
name	String	Destination name	X
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
rpflag	String	rpflag options	X
correction_result	String	Information about corrected guide points near the destination. (If the option is not set, correction_result will not be included in the response.) • none: No adjustment • building_entrance: Building entrance • parking: Parking lot entrance (Default: null. If omitted, no adjustment is applied.)	X
waypoints	Object[]	Stop point along the route. Up to 100 waypoints are allowed. The total route distance, including all waypoints, must be less than 1,500 km.	X
name	String	Waypoint name	X
x	Double	X coordinate (longitude)	O
y	Double	Y coordinate (latitude)	O
rpflag	String	rpflag options	X
correction_result	String	Information about corrected guide points near the waypoints. (If the option is not set, correction_result will not be included in the response.) • none: No adjustment • 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 restriction 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) Use multiple restriction options by connecting them like this: (Example: ["ferries", "motorway"])	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
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": "e95be80453a441989afad0068c646930",
    "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": 4000,
                    "toll": 0
                },
                "distance": 1852,
                "duration": 462
            },
            "sections": [
                {
                    "distance": 605,
                    "duration": 141
                },
                {
                    "distance": 1304,
                    "duration": 332
                }
            ]
        }
    ]
}

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