다크 모드
자전거 길찾기
하나의 출발지에서 여러 개의 경유지를 지나 하나의 목적지까지의 경로 정보를 제공합니다. 자전거 길찾기 API를 이용할 경우 경유지는 최대 5개까지 추가할 수 있습니다.
DANGER
Request
요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.
호출 방식
| Method | URL |
|---|---|
GET | https://apis-navi.kakaomobility.com/affiliate/bicycle/v1/directions |
요청 헤더(Header)
| Parameter | Description |
|---|---|
| Authorization | KakaoAK ${REST_API_KEY} {REST_API_KEY}: 카카오디벨로퍼스에서 발급 받은 REST API 키 |
| service | 서비스를 구분하는 임의의 문자열 |
| Content-Type | application/json |
요청 코드 예제
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 키 값요청에 대한 파라미터는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
origin | String | 출발지 경도, 위도 순서로 ${X좌표},${Y좌표} 형식으로 요청 (예: 127.111202,37.394912) | 필수 |
destination | String | 목적지 경도, 위도 순서로 ${X좌표},${Y좌표} 형식으로 요청 (예: 127.111202,37.394912) | 필수 |
waypoints | String | 경유지 정보. 최대 5개까지 허용 경도, 위도 순서로 ${X좌표},${Y좌표} 형식을 |로 연결하여 입력 (예: 127.111202,37.394912 | 127.112275,37.392815) | 선택 |
priority | String | 경로 탐색 우선순위 옵션 다음 중 하나: DISTANCE: 최단 경로MAIN_STREET: 큰길 우선BIKE_ROAD: 자전거 전용 도로 우선(기본값: DISTANCE) | 선택 |
summary | Boolean | 요약 정보만 제공 여부true: 요약 정보 제공false: 요약 정보 미제공(기본값: false) | 선택 |
default_speed | float | 도착 예상 시간(ETA) 측정 시 사용할 속도 설정 기본값: 0 (이 경우 15 km/h로 설정되고 0 이외의 숫자를 입력하면 해당 속도로 예상 시간이 측정됨.) 최솟값: 0, 최댓값 제한 없음. | 선택 |
Response
응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 요청 본문은 JSON 포맷으로 전달합니다.
응답 코드 예제
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
]
}
]
}
]
}
]
}요청 응답에 대한 객체 정보는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
trans_id | String | 경로 요청 ID | 필수 |
routes | Object[] | 경로 정보 | 필수 |
result_code | Int | 경로 탐색 결과 코드 | 필수 |
result_message | String | 경로 탐색 결과 메시지 | 필수 |
summary | Object | 경로 요약 정보 | 선택 |
distance | Int | 전체 검색 결과 거리(미터) | 필수 |
duration | Int | 목적지까지 소요 시간(초) | 필수 |
sections | Object[] | 구간별 경로 정보로 summary가 false로 설정된 경우에 정보가 제공됨.경유지가 존재할 경우 {경유지 수 + 1} 만큼의 섹션(경로 구간) 생성 (예: 경유지 수가 2개인 경우 총 3개의 섹션 정보가 생성, section1: 출발지 → 경유지 1 section2: 경유지 1 → 경유지 2 section3: 경유지 2 → 목적지) | 선택 |
distance | Int | 섹션 거리(미터) | 필수 |
duration | Int | 전체 검색 결과 이동 시간(초) | 필수 |
roads | Object[] | 도로 정보 | 필수 |
distance | Int | 도로 길이(미터) | 필수 |
duration | Int | 예상 이동 시간(초) | 필수 |
vertexes | Double[] | X, Y 좌표로 구성된 1차원 배열 (예: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] ) | 필수 |