다크 모드
자동차 길찾기
하나의 출발지에서 하나의 목적지까지로의 경로에 대한 상세 정보를 제공합니다. 경유지는 최대 5개까지 추가할 수 있으며 모든 경유지를 포함한 경로의 총 거리는 1,500 km 미만으로 설정해야 합니다.
DANGER
Request
요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.
호출 방식
| Method | URL |
|---|---|
GET | https://apis-navi.kakaomobility.com/affiliate/v1/directions |
요청 헤더(Header)
| Parameter | Description |
|---|---|
| Authorization | KakaoAK ${REST_API_KEY} {REST_API_KEY}: 카카오디벨로퍼스에서 발급 받은 REST API 키 |
| Content-Type | application/json |
요청 코드 예제
bash
curl -v -X GET "https://apis-navi.kakaomobility.com/affiliate/v1/directions?origin=127.11015314141542,37.39472714688412&destination=127.10824367964793,37.401937080111644" \
-H "Authorization: KakaoAK ${REST_API_KEY}" // 카카오디벨로퍼스에서 발급 받은 API 키 값요청에 대한 파라미터는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
origin | String | 출발지 다음 중 하나의 형식으로 요청: 1. ${X좌표},${Y좌표},name=${출발지명} (예: " 127.111202,37.394912,name=판교역") 2. ${X좌표},${Y좌표} (예: " 127.111202,37.394912") 3. ${X좌표},${Y좌표},${angle}(예:" 127.111202,37.394912,angle=90")angle: 출발지의 초기 진행 방향 지정. 0~360 범위의 정수를 입력(각도에 따른 방향: 0 = 북쪽, 90 = 동쪽, 180 = 남쪽, 270 = 서쪽 등 시계 방향으로 반영. 범위를 벗어난 값은 무시) | 필수 |
destination | String | 목적지 다음 중 하나의 형식으로 요청: 1. ${X좌표},${Y좌표},name=${목적지명} (예: " 127.111202,37.394912,name=판교역") 2. ${X좌표},${Y좌표} (예: " 127.111202,37.394912") 3. ${X좌표},${Y좌표},${point_correction}(예:" 127.111202,37.394912, correction_point=parking")point_correction: 경유지/목적지 주변의 안내 지점 보정 옵션• none: 보정 안 함(입력값을 생략하거나 null로 설정해도 동일하게 보정은 적용 안 됨.)• building_entrance: 건물 입구• parking: 주차장 입구(기본값: null, 입력 생략 시 보정 미적용) | 필수 |
waypoints | String | 경유지, 최대 5개까지 허용 모든 경유지를 포함한 경로의 총 거리는 1,500 km 미만으로 설정해야 함. 경유지 수만큼 아래 형식 중 하나를 선택하여 | 또는 %7C로 구분해 입력:1. ${X좌표},${Y좌표},name=${경유지명}2. ${X좌표},${Y좌표}3. ${X좌표},${Y좌표},${point_correction}(예:" 127.111202,37.394912,name=판교역|")point_correction: 경유지/목적지 주변의 안내 지점 보정 옵션• none: 보정 안 함(입력값을 생략하거나 null로 설정해도 동일하게 보정은 보정은 적용 안 됨)• building_entrance: 건물 입구• parking: 주차장 입구(기본값: null, 입력 생략 시 보정 미적용) | 선택 |
priority | String | 경로 탐색 우선순위 옵션 다음 중 하나: RECOMMEND: 추천 경로TIME: 최단 시간DISTANCE: 최단 경로MAIN_ROAD: 큰길 우선NO_TRAFFIC_INFO: 실시간 교통정보를 반영하지 않은 가장 빠른 경로(기본값: RECOMMEND) | 선택 |
avoid | String | 경로 탐색 제한 옵션 다음 값 사용 가능: ferries: 페리 항로toll: 유료 도로motorway: 자동차 전용 도로schoolzone: 어린이 보호 구역uturn: 유턴(기본값: null)여러 개의 제한 옵션을 사용하려면 |(또는 인코딩 된 문자인 %7C)로 연결(예: avoid=motorway|ferries) | 선택 |
roadevent | Int | 유고(교통사고, 행사, 재난, 도로 공사 등의 교통 장애)로 인한 도로 통제 정보 반영 옵션0: 전체 차선 통제(도로 전체 통제) 정보를 반영1: 출발지 및 목적지 주변의 전체 차선 통제 정보 반영 안 함2: 모든 구간의 전체 차선 통제 정보 반영 안 함(기본값: 0) | 선택 |
alternatives | Boolean | 대안 경로 제공 여부true: 대안 경로 제공false: 대안 경로 미제공(기본값: false) | 선택 |
road_details | Boolean | 상세 도로 정보 제공 여부true: 상세 도로 정보 제공false: 상세 도로 정보 미제공(기본값: false) | 선택 |
road_details_extra_info | String | 상세 도로 정보 추가 정보. road_details 옵션이 true 인 경우에 적용됨상세 도로 정보 추가 정보 • safety: 안전운행• roadevent: 유고정보(예: road_details_extra_info=safety 또는 road_details_extra_info=safety|roadevent) | 선택 |
car_type | Int | 차종 (기본값: 1) | 선택 |
car_length | Int | 차량 길이(cm)-1: 값 없음 | 선택 |
car_width | Int | 차량 너비(cm)-1: 값 없음 | 선택 |
car_height | Int | 차량 높이(cm)-1: 값 없음 | 선택 |
car_weight | Int | 차량 중량(0.1톤 단위)-1: 값 없음 | 선택 |
car_fuel | String | 차량 유종 정보 다음 중 하나: GASOLINE: 휘발유DIESEL: 경유LPG: LPG(기본값: GASOLINE) | 선택 |
car_hipass | Boolean | 하이패스 장착 여부true: 하이패스 장착false: 하이패스 미장착(기본값: false) | 선택 |
summary | Boolean | 경로 정보 응답 범위 설정true: 요약 정보만 반환 (sections의 bound, roads, guides 정보 제외)false: 요약 정보와 상세 정보 반환(sections의 bound, roads, guides 정보 포함)(기본값: false) | 선택 |
Response
응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 요청 본문은 JSON 포맷으로 전달합니다.
응답 코드 예제
bash
{
"trans_id": "890c12877fc743138c40b3844c813eb9",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"summary": {
"origin": {
"name": "",
"x": 127.11015051307636,
"y": 37.394725518530834
},
"destination": {
"name": "",
"x": 127.10823557165544,
"y": 37.401928707331656
},
"waypoints": [],
"priority": "RECOMMEND",
"bound": {
"min_x": 127.10833536148644,
"min_y": 37.39445954360996,
"max_x": 127.1098222529551,
"max_y": 37.40242724407785
},
"fare": {
"taxi": 3800,
"toll": 0
},
"distance": 1033,
"duration": 297
},
"sections": [
{
"distance": 1033,
"duration": 297,
"bound": {
"min_x": 127.10824109988312,
"min_y": 37.394469584427156,
"max_x": 127.10991634747967,
"max_y": 37.40242613861426
},
"roads": [
{
"name": "",
"distance": 22,
"duration": 5,
"traffic_speed": 16,
"traffic_state": 0,
"vertexes": [
127.10991634747967,
37.39447145478345,
127.10966790676201,
37.394469584427156
]
},
{
"name": "판교역로",
"distance": 883,
"duration": 224,
"traffic_speed": 12,
"traffic_state": 2,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10967141980313,
37.39512739646385,
127.10968100356395,
37.396226781360426,
127.10967417816033,
37.39775855885587,
127.10968323318781,
37.39794785293074,
127.10967534594126,
37.39861458950405,
127.10967214334856,
37.399840028043634,
127.1096931266438,
37.40093048716485,
127.10967543155922,
37.40242613861426
]
},
{
"name": "판교역로241번길",
"distance": 128,
"duration": 68,
"traffic_speed": 16,
"traffic_state": 2,
"vertexes": [
127.10967543155922,
37.40242613861426,
127.10860261294675,
37.40240904474889,
127.10824109988312,
37.402415329497174
]
}
],
"guides": [
{
"name": "출발지",
"x": 127.10991634747967,
"y": 37.39447145478345,
"distance": 0,
"duration": 0,
"type": 100,
"guidance": "출발지",
"road_index": 0
},
{
"name": "",
"x": 127.10966790676201,
"y": 37.394469584427156,
"distance": 22,
"duration": 5,
"type": 2,
"guidance": "우회전",
"road_index": 1
},
{
"name": "",
"x": 127.10967543155922,
"y": 37.40242613861426,
"distance": 883,
"duration": 224,
"type": 1,
"guidance": "좌회전",
"road_index": 2
},
{
"name": "목적지",
"x": 127.10824109988312,
"y": 37.402415329497174,
"distance": 128,
"duration": 68,
"type": 101,
"guidance": "목적지",
"road_index": -1
}
]
}
]
}
]
}요청 응답에 대한 객체 정보는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
trans_id | String | 경로 요청 ID | 필수 |
routes | Object[] | 경로 정보alternatives가 true인 경우 한 개 이상의 경로 제공 가능 | 필수 |
result_code | Int | 경로 탐색 결과 코드 | 필수 |
result_msg | String | 경로 탐색 결과 메시지 | 필수 |
summary | Object | 경로 요약 정보 | 필수 |
origin | Object | 출발지 정보 | 필수 |
name | String | 출발지 이름 | 필수 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
destination | Object | 목적지 정보 | 필수 |
name | String | 목적지 이름 | 필수 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
correction_result | String | 목적지 주변에서 보정된 안내 지점에 대한 정보(point_correction의 옵션값이 설정되지 않은 경우, 응답에는 correction_result가 포함되지 않음)• none: 보정 안 함• building_entrance: 건물 입구• parking: 주차장 입구 | 필수 |
waypoints | Object[] | 경유지 정보 | 필수 |
name | String | 경유지 이름 | 필수 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
correction_result | String | 경유지 주변에서 보정된 안내 지점에 대한 정보(point_correction의 옵션값이 설정되지 않은 경우, 응답에는 correction_result가 포함되지 않음)• none: 보정 안 함• building_entrance: 건물 입구• parking: 주차장 입구 | 필수 |
priority | String | 경로 탐색 우선순위 옵션 | 필수 |
bound | Object | 모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box) | 선택 |
min_x | Double | 바운딩 박스 왼쪽 하단의 X 좌표 | 필수 |
min_y | Double | 바운딩 박스 왼쪽 하단의 Y 좌표 | 필수 |
max_x | Double | 바운딩 박스 오른쪽 상단의 X 좌표 | 필수 |
max_y | Double | 바운딩 박스 오른쪽 상단의 Y 좌표 | 필수 |
fare | Object | 요금 정보 | 필수 |
taxi | Int | 택시 요금(원) | 필수 |
toll | Int | 통행 요금(원) | 필수 |
distance | Int | 전체 검색 결과 거리(미터) | 필수 |
duration | Int | 목적지까지 소요 시간(초) | 필수 |
sections | Object[] | 구간별 경로 정보 경유지가 존재할 경우 {경유지 수 + 1} 만큼의 섹션(경로 구간) 생성 (예: 경유지 수가 2개인 경우 총 3개의 섹션 정보가 생성, section1: 출발지 → 경유지 1 section2: 경유지 1 → 경유지 2 section3: 경유지 2 → 목적지) | 필수 |
distance | Int | 섹션 거리(미터) | 필수 |
duration | Int | 전체 검색 결과 이동 시간(초) | 필수 |
bound | Object | 모든 경로를 포함하는 사각형의 바운딩 박스(Bounding box) summary가 false인 경우에만 제공 | 선택 |
min_x | Double | 바운딩 박스 왼쪽 하단의 X 좌표 | 필수 |
min_y | Double | 바운딩 박스 왼쪽 하단의 Y 좌표 | 필수 |
max_x | Double | 바운딩 박스 오른쪽 상단의 X 좌표 | 필수 |
max_y | Double | 바운딩 박스 오른쪽 상단의 Y 좌표 | 필수 |
roads | Object[] | 도로 정보summary가 false인 경우에만 제공 | 선택 |
name | String | 도로명 | 필수 |
distance | Int | 도로 길이(미터) | 필수 |
duration | Int | 예상 이동 시간(초) 현재 예상 이동 시간 및 실제 이동 시간은 동일한 값으로 설정 | 필수 |
traffic_speed | Double | 현재 교통 정보 속도(km/h) | 필수 |
traffic_state | Int | 현재 교통 정보 상태 | 필수 |
vertexes | Double[] | X, Y 좌표로 구성된 1차원 배열 (예: [127.10966790676201, 37.394469584427156, 127.10967141980313, 37.39512739646385] ) | 필수 |
guides | Object[] | 안내 정보summary가 false인 경우에만 제공 | 선택 |
name | String | 명칭 | 필수 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
distance | Int | 이전 가이드 지점부터 현재 가이드 지점까지 거리(미터) | 필수 |
duration | Int | 이전 가이드 지점부터 현재 가이드 지점까지 시간(초) | 필수 |
type | Int | 안내 타입 | 필수 |
guidance | String | 안내 문구 | 필수 |
road_index | Int | 현재 가이드에 대한 링크 인덱스 | 필수 |