🌐 한국어

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

Request Headers

Parameter	Description
Authorization	KakaoAK ${REST_API_KEY} {REST_API_KEY}: The API key issued from Kakao Developers
service	An arbitrary string that distinguishes the service
Content-Type	application/json

Sample request

curl -v -X POST "https://apis-navi.kakaomobility.com/affiliate/walking/v1/waypoints/directions" \
-H "accept: application/json" \
-H "service: test" \
-H "Content-Type: application/json" \
-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:

Parameters

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 navigation. Use one of the following: DISTANCE: The shortest route MAIN_STREET: Prioritizes main streets (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 (excludes roads in sections). false: Returns summary information together with detailed route information (includes roads in sections). (Default: false)	X
default_speed	float	Set the speed to be used when calculating the estimated time of arrival (ETA). Default: 0 (in this case, set to 4 km/h. If a number other than 0 is entered, the estimated time is measured at that speed.) Minimum value: 0, no maximum value 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

{
"trans_id": "0197c34284307594a2b08e1e6f19798c",
"routes": [
  {
    "result_code": 0,
    "result_message": "길찾기 성공",
    "summary": {
      "distance": 350,
      "duration": 355
    },
    "sections": [
      {
        "distance": 126,
        "duration": 153,
        "roads": [
          {
            "distance": 33,
            "duration": 30,
            "vertexes": [
              127.10908451095504,
              37.39606876648597,
              127.10935554290191,
              37.39607080825963,
              127.10943512691682,
              37.396026353876806
            ]
          },
          {
            "distance": 44,
            "duration": 79,
            "vertexes": [
              127.10943512691682,
              37.396026353876806,
              127.10993180551668,
              37.39604811509296
            ]
          },
          {
            "distance": 49,
            "duration": 44,
            "vertexes": [
              127.10993180551668,
              37.39604811509296,
              127.10986468685842,
              37.39599354529187,
              127.10986905550754,
              37.39562413701159
            ]
          }
        ]
      },
      {
        "distance": 61,
        "duration": 55,
        "roads": [
          {
            "distance": 61,
            "duration": 55,
            "vertexes": [
              127.10986905550754,
              37.39562413701159,
              127.10988684790803,
              37.39507461453519
            ]
          }
        ]
      },
      {
        "distance": 163,
        "duration": 147,
        "roads": [
          {
            "distance": 36,
            "duration": 32,
            "vertexes": [
              127.10988684790803,
              37.39507461453519,
              127.10989057703102,
              37.39475926595345
            ]
          },
          {
            "distance": 93,
            "duration": 84,
            "vertexes": [
              127.10989057703102,
              37.39475926595345,
              127.10988929942614,
              37.393912244671725
            ]
          },
          {
            "distance": 10,
            "duration": 9,
            "vertexes": [
              127.10988929942614,
              37.393912244671725,
              127.10988961905323,
              37.39388521478862,
              127.10993532242595,
              37.39384050499694
            ]
          },
          {
            "distance": 24,
            "duration": 22,
            "vertexes": [
              127.10993532242595,
              37.39384050499694,
              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. Only returned if 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	O
vertexes	Double[]	One-dimensional array that includes X and Y coordinates (Example: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] )	O