Multi-Waypoint Directions

This API provides detailed route information from a single origin to a single destination via multiple waypoints. You can add up to 100 waypoints.

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/bicycle/v1/waypoints/directions

Request Headers

Parameter	Description
Authorization	KakaoAK ${REST_API_KEY} {REST_API_KEY}: The API key issued from Kakao Developers
service	Arbitrary string to identify the service
Content-Type	`application/json`

Sample request

bash

curl -v -X POST "https://apis-navi.kakaomobility.com/affiliate/bicycle/v1/waypoints/directions" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "service: test" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \  // The API key issued from Kakao Developers
-d '{
"origin": {
  "x": 127.10909763718492,
  "y": 37.39589794700353
},
"waypoints": [
  {
    "x": 127.10995909939992,
    "y": 37.3956341116223
  },
  {
    "x": 127.10989784118405,
    "y": 37.395083994105576
  }
],
"destination": {
  "x": 127.11022639567598,
  "y": 37.39404121844038
}
}'

The request parameters are as follows:

Name	Type	Description	Required
`origin`	Object	Departure point	O
`x`	Double	X coordinate (longitude)	O
`y`	Double	Y coordinate (latitude)	O
`destination`	Object[]	Arrival point	O
`x`	Double	X coordinate (longitude)	O
`y`	Double	Y coordinate (latitude)	O
`waypoints`	Object[]	Stop point along the route. Up to 100 waypoints are allowed.	X
`x`	Double	X coordinate (longitude)	O
`y`	Double	Y coordinate (latitude)	O
`priority`	String	Set priority options for bicycle route search. Use one of the following: `DISTANCE`: The shortest route `MAIN_STREET`: Prioritizes main roads `BIKE_ROAD`: Prioritizes bicycle-only roads (Default: `DISTANCE`)	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 `false`: Returns summary information together with detailed route information (Default: `false`)	X
`default_speed`	float	Speed setting to be used when calculating estimated time of arrival (ETA). Default: 0 (In this case, it is set to 15 km/h. If a number other than 0 is entered, the estimated time is calculated at that speed.) Minimum: 0, Maximum: No limit.	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

bash

{
"trans_id": "0197c35c0aa875fea2f6997ff5bf9917",
"routes": [
  {
    "result_code": 0,
    "result_message": "길찾기 성공",
    "summary": {
      "distance": 581,
      "duration": 161
    },
    "sections": [
      {
        "distance": 126,
        "duration": 41,
        "roads": [
          {
            "distance": 33,
            "duration": 8,
            "vertexes": [
              127.10908451095504,
              37.39606876648597,
              127.10935554290191,
              37.39607080825963,
              127.10943512691682,
              37.396026353876806
            ]
          },
          {
            "distance": 44,
            "duration": 21,
            "vertexes": [
              127.10943512691682,
              37.396026353876806,
              127.10993180551668,
              37.39604811509296
            ]
          },
          {
            "distance": 49,
            "duration": 12,
            "vertexes": [
              127.10993180551668,
              37.39604811509296,
              127.10986468685842,
              37.39599354529187,
              127.10986905550754,
              37.39562413701159
            ]
          }
        ]
      },
      {
        "distance": 61,
        "duration": 15,
        "roads": [
          {
            "distance": 61,
            "duration": 15,
            "vertexes": [
              127.10986905550754,
              37.39562413701159,
              127.10988684790803,
              37.39507461453519
            ]
          }
        ]
      },
      {
        "distance": 394,
        "duration": 105,
        "roads": [
          {
            "distance": 36,
            "duration": 9,
            "vertexes": [
              127.10988684790803,
              37.39507461453519,
              127.10989057703102,
              37.39475926595345
            ]
          },
          {
            "distance": 93,
            "duration": 22,
            "vertexes": [
              127.10989057703102,
              37.39475926595345,
              127.10988929942614,
              37.393912244671725
            ]
          },
          {
            "distance": 10,
            "duration": 2,
            "vertexes": [
              127.10988929942614,
              37.393912244671725,
              127.10988961905323,
              37.39388521478862,
              127.10993532242595,
              37.39384050499694
            ]
          },
          {
            "distance": 21,
            "duration": 10,
            "vertexes": [
              127.10993532242595,
              37.39384050499694,
              127.10992626704797,
              37.39365121080641
            ]
          },
          {
            "distance": 116,
            "duration": 28,
            "vertexes": [
              127.10992626704797,
              37.39365121080641,
              127.11124771867432,
              37.39364312870764
            ]
          },
          {
            "distance": 26,
            "duration": 12,
            "vertexes": [
              127.11124771867432,
              37.39364312870764,
              127.11124495280912,
              37.39387738778665
            ]
          },
          {
            "distance": 22,
            "duration": 5,
            "vertexes": [
              127.11124495280912,
              37.39387738778665,
              127.11098522129426,
              37.393875435346345
            ]
          },
          {
            "distance": 70,
            "duration": 17,
            "vertexes": [
              127.11098522129426,
              37.393875435346345,
              127.11057868506042,
              37.39387237820778,
              127.11045489156606,
              37.3938354039534,
              127.11020645291707,
              37.39383353475566
            ]
          }
        ]
      }
    ]
  }
]
}

The response object information is as follows:

Name	Type	Description	Required
`trans_id`	String	Unique identifier of a direction request	O
`routes`	Object[]	Route Information	O
`result_code`	Int	Result code	O
`result_message`	String	Result message	O
`summary`	Object	Summary information of directions	X
`distance`	Int	Total distance in meters	O
`duration`	Int	Total required time in seconds	O
`sections`	Object[]	Route data by section, provided when `summary` is set to `false`. 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)	X
`distance`	Int	Distance between sections in meters	O
`duration`	Int	Total required time in seconds	O
`roads`	Object[]	Road information	O
`distance`	Int	Road distance in meters	O
`duration`	Int	Estimated travel time in seconds Currently, the estimated travel time and actual required time are set to the same value.	O
`vertexes`	Double[]	One-dimensional array that includes X and Y coordinates (Example: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] )	O

Multi-Waypoint Directions ​

Request ​

Request Method ​

Request Headers ​

Sample request ​

Response ​