Multi-Origin Directions

This API provides route information from one or more origins to a single destination. You can set up to 100 origins.

DANGER

You need a REST API key to use this API. To register an app and get a REST API key, see Getting Started.

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/origins/directions

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 POST "https://apis-navi.kakaomobility.com/affiliate/bicycle/v1/origins/directions" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \  // The REST API key issued from Kakao Developers
-d '{
"origins": [
  {
    "x": 127.10909763718492,
    "y": 37.39589794700353
  },
  {
    "x": 127.11374021945907,
    "y": 37.39583371633596
  }
],
"destination": {
  "x": 127.11022639567598,
  "y": 37.39404121844038
}
}'

The request parameters are as follows:

Name	Type	Description	Required
origins	Object[]	Origin. Up to 100 origins are allowed.	Required
x	Double	X coordinate (longitude)	Required
y	Double	Y coordinate (latitude)	Required
destination	Object	Destination	Required
x	Double	X coordinate (longitude)	Required
y	Double	Y coordinate (latitude)	Required
radius	Integer	Route search radius in meters between origin and destination (Default: 2000, Maximum: 12000) If no value is entered, or if 0 or a negative value is entered, the default value is set. If a value exceeding the maximum is entered, it is fixed to the maximum value of 12000.	Optional
priority	String	Route search priority option Use one of the following: DISTANCE: Shortest route MAIN_STREET: Main street priority BIKE_ROAD: Bicycle-only road priority (Default: DISTANCE)	Optional
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)	Optional
default_speed	float	Speed setting to use when measuring Estimated Time of Arrival (ETA) Default: 0 (In this case, it is set to 15 km/h, and if a number other than 0 is entered, the estimated time is measured at that speed.) Minimum: 0, Maximum: No limit.	Optional

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": "01872690b462710f821af295cecf28b9",
"routes": [
  {
    "result_code": 0,
    "result_message": "성공",
    "summary": {
      "distance": 336,
      "duration": 337
    },
    "sections": [
      {
        "distance": 336,
        "duration": 337,
        "roads": [
          {
            "distance": 30,
            "duration": 27,
            "vertexes": [
              127.10908798259713,
              37.396048904441905,
              127.10939289367556,
              37.39605119783509,
              127.10941569256795,
              37.39603334775928
            ]
          },
// … Code omitted
          {
            "distance": 93,
            "duration": 84,
            "vertexes": [
              127.11123624251599,
              37.39392949433143,
              127.1106829007183,
              37.393925340492096,
              127.11049166915824,
              37.39386082897841,
              127.11020924587568,
              37.393867718189924
            ]
          }
        ]
      }
    ]
  }
]
}

The response object information is as follows:

Name	Type	Description	Required
trans_id	String	Unique identifier of a route request	Required
routes	Object[]	Route information	Required
result_code	Int	Route search result code	Required
result_message	String	Route search result message	Required
summary	Object	Route summary information	Optional
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. Returned when summary is set to false. When waypoints exist, {number of waypoints + 1} sections (route segments) are created (Example: If there are 2 waypoints, a total of 3 sections are created, section1: origin → waypoint 1 section2: waypoint 1 → waypoint 2 section3: waypoint 2 → destination)	Optional
distance	Int	Section distance in meters	Required
duration	Int	Total travel time of the search result in seconds	Required
roads	Object[]	Road information	Required
distance	Int	Road length in meters	Required
duration	Int	Estimated travel time in seconds Currently, estimated travel time and actual travel time are set to the same value	Required
vertexes	Double[]	One-dimensional array of X and Y coordinates (Example: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] )	Required