Cycling Directions

This API provides detailed route information from a single origin through multiple waypoints to a single destination. When using the Cycling Directions API, you can add up to 5 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
`GET`	https://apis-navi.kakaomobility.com/affiliate/bicycle/v1/directions

Request Headers

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

Sample request

bash

curl -v -X GET "https://apis-navi.kakaomobility.com/affiliate/bicycle/v1/directions?origin=127.11015314141542,37.39472714688412&destination=127.10824367964793,37.401937080111644&waypoints=&radius=5000&priority=DISTANCE&summary=false" \
  -H 'accept: application/json' \
  -H 'service: test' \
  -H "Authorization: KakaoAK ${REST_API_KEY}" // API key issued from Kakao Developers

The request parameters are as follows.

Parameters

Name	Type	Description	Required
`origin`	String	Departure point Request in the format ${X coordinate},${Y coordinate} with longitude and latitude in order (Example: 127.111202,37.394912)	O
`destination`	String	Arrival point Request in the format ${X coordinate},${Y coordinate} with longitude and latitude in order (Example: 127.111202,37.394912)	O
`waypoints`	String	Waypoint information. Up to 5 waypoints are allowed Connect multiple waypoints with \| in the format ${X coordinate},${Y coordinate} (Example: 127.111202,37.394912 \| 127.112275,37.392815)	X
`priority`	String	Route search priority option Use one of the following: `DISTANCE`: Shortest route `MAIN_STREET`: Prioritize main roads `BIKE_ROAD`: Prioritize 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 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 value: 0, no maximum 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": "0197c35754fc7e988905e78702f8daa8",
"routes": [
  {
    "result_code": 0,
    "result_message": "길찾기 성공",
    "summary": {
      "distance": 1441,
      "duration": 363
    },
    "sections": [
      {
        "distance": 293,
        "duration": 81,
        "roads": [
          {
            "distance": 20,
            "duration": 5,
            "vertexes": [
              126.992479359776,
              37.5641166429451,
              126.99262455176134,
              37.56426204879206
            ]
          },
          {
            "distance": 10,
            "duration": 2,
            "vertexes": [
              126.99262455176134,
              37.56426204879206,
              126.99273785260915,
              37.5642540050905
            ]
          },
          {
            "distance": 32,
            "duration": 15,
            "vertexes": [
              126.99273785260915,
              37.5642540050905,
              126.99309978460478,
              37.564275113363486
            ]
          },
          {
            "distance": 82,
            "duration": 20,
            "vertexes": [
              126.99309978460478,
              37.564275113363486,
              126.99401702394601,
              37.564246891073104
            ]
          },
          {
            "distance": 10,
            "duration": 2,
            "vertexes": [
              126.99401702394601,
              37.564246891073104,
              126.9941303246516,
              37.56423884603255
            ]
          },
          {
            "distance": 19,
            "duration": 9,
            "vertexes": [
              126.9941303246516,
              37.56423884603255,
              126.99415065895657,
              37.564410217438784
            ]
          },
          {
            "distance": 8,
            "duration": 2,
            "vertexes": [
              126.99415065895657,
              37.564410217438784,
              126.99405999395755,
              37.564418455371786
            ]
          },
          {
            "distance": 14,
            "duration": 3,
            "vertexes": [
              126.99405999395755,
              37.564418455371786,
              126.99410369102182,
              37.56453596327218
            ]
          },
          {
            "distance": 26,
            "duration": 6,
            "vertexes": [
              126.99410369102182,
              37.56453596327218,
              126.99419132781937,
              37.56475296023
            ]
          },
          {
            "distance": 29,
            "duration": 7,
            "vertexes": [
              126.99419132781937,
              37.56475296023,
              126.9942897986855,
              37.56500609112572
            ]
          },
          {
            "distance": 29,
            "duration": 7,
            "vertexes": [
              126.9942897986855,
              37.56500609112572,
              126.99442234564174,
              37.56525050175984
            ]
          },
          {
            "distance": 14,
            "duration": 3,
            "vertexes": [
              126.99442234564174,
              37.56525050175984,
              126.99456996543414,
              37.56521571733765
            ]
          }
        ]
      },
      {
        "distance": 220,
        "duration": 52,
        "roads": [
          {
            "distance": 14,
            "duration": 3,
            "vertexes": [
              126.99456996543414,
              37.56521571733765,
              126.99442234564174,
              37.56525050175984
            ]
          },
          {
            "distance": 17,
            "duration": 4,
            "vertexes": [
              126.99442234564174,
              37.56525050175984,
              126.99448843778727,
              37.56538622111689
            ]
          },
          {
            "distance": 16,
            "duration": 4,
            "vertexes": [
              126.99448843778727,
              37.56538622111689,
              126.99454321201681,
              37.56552184404442
            ]
          },
          {
            "distance": 11,
            "duration": 3,
            "vertexes": [
              126.99454321201681,
              37.56552184404442,
              126.994575834464,
              37.565621236581535
            ]
          },
          {
            "distance": 39,
            "duration": 9,
            "vertexes": [
              126.994575834464,
              37.565621236581535,
              126.99472980906961,
              37.56595593361724
            ]
          },
          {
            "distance": 16,
            "duration": 4,
            "vertexes": [
              126.99472980906961,
              37.56595593361724,
              126.99480734167517,
              37.566082739776654
            ]
          },
          {
            "distance": 34,
            "duration": 8,
            "vertexes": [
              126.99480734167517,
              37.566082739776654,
              126.99497336279838,
              37.56636347648975
            ]
          },
          {
            "distance": 17,
            "duration": 4,
            "vertexes": [
              126.99497336279838,
              37.56636347648975,
              126.99516565254011,
              37.56637412374829
            ]
          },
          {
            "distance": 22,
            "duration": 5,
            "vertexes": [
              126.99516565254011,
              37.56637412374829,
              126.99527883536439,
              37.56637508705016,
              126.99541441277243,
              37.56639426166438
            ]
          },
          {
            "distance": 32,
            "duration": 8,
            "vertexes": [
              126.99541441277243,
              37.56639426166438,
              126.995395648073,
              37.566105768311
            ]
          },
          {
            "distance": 2,
            "duration": 0,
            "vertexes": [
              126.995395648073,
              37.566105768311,
              126.9953958900632,
              37.56608774951504
            ]
          }
        ]
      },
      {
        "distance": 928,
        "duration": 230,
        "roads": [
          {
            "distance": 14,
            "duration": 3,
            "vertexes": [
              126.9953958900632,
              37.56608774951504,
              126.99540890220916,
              37.56596171425369
            ]
          },
          {
            "distance": 58,
            "duration": 14,
            "vertexes": [
              126.99540890220916,
              37.56596171425369,
              126.99546107129092,
              37.5654485637618
            ]
          },
          {
            "distance": 7,
            "duration": 2,
            "vertexes": [
              126.99546107129092,
              37.5654485637618,
              126.99547323631413,
              37.56538559427187
            ]
          },
          {
            "distance": 9,
            "duration": 2,
            "vertexes": [
              126.99547323631413,
              37.56538559427187,
              126.99548564327739,
              37.565304605980884
            ]
          },
          {
            "distance": 86,
            "duration": 21,
            "vertexes": [
              126.99548564327739,
              37.565304605980884,
              126.99454321201681,
              37.56552184404442
            ]
          },
          {
            "distance": 16,
            "duration": 4,
            "vertexes": [
              126.99454321201681,
              37.56552184404442,
              126.99448843778727,
              37.56538622111689
            ]
          },
          {
            "distance": 17,
            "duration": 4,
            "vertexes": [
              126.99448843778727,
              37.56538622111689,
              126.99442234564174,
              37.56525050175984
            ]
          },
          {
            "distance": 29,
            "duration": 7,
            "vertexes": [
              126.99442234564174,
              37.56525050175984,
              126.9942897986855,
              37.56500609112572
            ]
          },
          {
            "distance": 29,
            "duration": 7,
            "vertexes": [
              126.9942897986855,
              37.56500609112572,
              126.99419132781937,
              37.56475296023
            ]
          },
          {
            "distance": 26,
            "duration": 6,
            "vertexes": [
              126.99419132781937,
              37.56475296023,
              126.99410369102182,
              37.56453596327218
            ]
          },
          {
            "distance": 14,
            "duration": 3,
            "vertexes": [
              126.99410369102182,
              37.56453596327218,
              126.99405999395755,
              37.564418455371786
            ]
          },
          {
            "distance": 57,
            "duration": 14,
            "vertexes": [
              126.99405999395755,
              37.564418455371786,
              126.9934257021247,
              37.56444909075953
            ]
          },
          {
            "distance": 35,
            "duration": 8,
            "vertexes": [
              126.9934257021247,
              37.56444909075953,
              126.99313119201484,
              37.56446460022759,
              126.99302896632213,
              37.56449075962704
            ]
          },
          {
            "distance": 37,
            "duration": 18,
            "vertexes": [
              126.99302896632213,
              37.56449075962704,
              126.99273785260915,
              37.5642540050905
            ]
          },
          {
            "distance": 76,
            "duration": 18,
            "vertexes": [
              126.99273785260915,
              37.5642540050905,
              126.99277229168005,
              37.56421825720251,
              126.99284881115113,
              37.56357916955021
            ]
          },
          {
            "distance": 38,
            "duration": 9,
            "vertexes": [
              126.99284881115113,
              37.56357916955021,
              126.99289869136155,
              37.56323719873073
            ]
          },
          {
            "distance": 50,
            "duration": 12,
            "vertexes": [
              126.99289869136155,
              37.56323719873073,
              126.99296122284451,
              37.562796221045375
            ]
          },
          {
            "distance": 11,
            "duration": 3,
            "vertexes": [
              126.99296122284451,
              37.562796221045375,
              126.99297387457189,
              37.562697214223334
            ]
          },
          {
            "distance": 50,
            "duration": 12,
            "vertexes": [
              126.99297387457189,
              37.562697214223334,
              126.9930252087004,
              37.56224713051655
            ]
          },
          {
            "distance": 67,
            "duration": 16,
            "vertexes": [
              126.9930252087004,
              37.56224713051655,
              126.99226729031004,
              37.56221363226412
            ]
          },
          {
            "distance": 56,
            "duration": 13,
            "vertexes": [
              126.99226729031004,
              37.56221363226412,
              126.99229283803129,
              37.56199759997831,
              126.99227408609767,
              37.561709106105894
            ]
          },
          {
            "distance": 52,
            "duration": 12,
            "vertexes": [
              126.99227408609767,
              37.561709106105894,
              126.99223512633834,
              37.56124023107781
            ]
          },
          {
            "distance": 55,
            "duration": 13,
            "vertexes": [
              126.99223512633834,
              37.56124023107781,
              126.99185008872628,
              37.561254964659746,
              126.9916126641763,
              37.561234916142325
            ]
          },
          {
            "distance": 39,
            "duration": 9,
            "vertexes": [
              126.9916126641763,
              37.561234916142325,
              126.99116008600868,
              37.561222039280274
            ]
          }
        ]
      }
    ]
  }
]
}

The response object information is as follows.

Response object

Name	Type	Description	Required
`trans_id`	String	Unique identifier of a route request	O
`routes`	Object[]	Route information	O
`result_code`	Int	Result code for route search	O
`result_message`	String	Result message for route search	O
`summary`	Object	Route summary information	X
`distance`	Int	Total search result distance (meters)	O
`duration`	Int	Total required time to destination (seconds)	O
`sections`	Object[]	Route information by section. Information is provided when `summary` is set to `false` If waypoints exist, sections are created as many as {number of waypoints + 1} (Example: If the number of waypoints is 2, three sections are created: section1: origin → waypoint 1 section2: waypoint 1 → waypoint 2 section3: waypoint 2 → destination)	X
`distance`	Int	Section distance (meters)	O
`duration`	Int	Total search result travel time (seconds)	O
`roads`	Object[]	Road information	O
`distance`	Int	Road distance (meters)	O
`duration`	Int	Estimated travel time (seconds)	O
`vertexes`	Double[]	One-dimensional array composed of X and Y coordinates (Example: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385])	O

Cycling Directions ​

Request ​

Request Method ​

Request Headers ​

Sample request ​

Parameters ​

Response ​

Sample response ​

Response object ​