Request 링크 복사
요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.
호출 방식 링크 복사
표 1
호출 방식
| Method | URL |
|---|---|
POST | https://apis-navi.kakaomobility.com/v1/waypoints/directions |
요청 헤더(Header) 링크 복사
표 2
요청 헤더
| Parameter | Description |
|---|---|
| Authorization | KakaoAK ${REST_API_KEY} {REST_API_KEY}: 카카오디벨로퍼스에서 발급 받은 REST API 키 |
| Content-Type | application/json |
요청 코드 예제 링크 복사
curl -v -X POST "https://apis-navi.kakaomobility.com/v1/waypoints/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \ // 카카오디벨로퍼스에서 발급 받은 API 키 값
-d '{
"origin": {
"x": "127.11024293202674",
"y": " 37.394348634049784",
"angle": 270
},
"destination": {
"x": "127.10860518470294",
"y": "37.401999820065534"
},
"waypoints": [
{
"name": "name0",
"x": 127.11341936045922,
"y": 37.39639094915999
}
],
"priority": "RECOMMEND",
"car_fuel": "GASOLINE",
"car_hipass": false,
"alternatives": false,
"road_details": false,
"summary": false
}'
curl -v -X POST "https://apis-navi.kakaomobility.com/v1/waypoints/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \ // 카카오디벨로퍼스에서 발급 받은 API 키 값
-d '{
"origin": {
"x": "127.11024293202674",
"y": " 37.394348634049784",
"angle": 270
},
"destination": {
"x": "127.10860518470294",
"y": "37.401999820065534"
},
"waypoints": [
{
"name": "name0",
"x": 127.11341936045922,
"y": 37.39639094915999
}
],
"priority": "RECOMMEND",
"car_fuel": "GASOLINE",
"car_hipass": false,
"alternatives": false,
"road_details": false,
"summary": false
}'
코드가 숨겨졌습니다.
요청에 대한 파라미터는 다음과 같습니다.
표 3
요청 파라미터
| Name | Type | Description | Required |
|---|---|---|---|
origin | Object | 출발지 | 필수 |
name | String | 출발지 이름 | 선택 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
angle | Int | 출발지의 초기 진행 방향 지정 0~360 범위의 정수 입력. (각도에 따른 방향: 0 = 북쪽, 90 = 동쪽, 180 = 남쪽, 270 = 서쪽 등 시계 방향으로 반영. 범위를 벗어난 값은 무시) | 선택 |
destination | Object | 목적지 | 필수 |
name | String | 목적지 이름 | 선택 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
waypoints | Object[] | 경유지, 최대 30개까지 허용 모든 경유지를 포함한 경로의 총 거리는 1,500 km 미만으로 설정해야 함. | 선택 |
name | String | 경유지 이름 | 선택 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
priority | String | 경로 탐색 우선순위 옵션 다음 중 하나: RECOMMEND: 추천 경로TIME: 최단 시간DISTANCE: 최단 경로(기본값: RECOMMEND) | 선택 |
avoid | String[] | 경로 탐색 제한 옵션 다음 값 사용 가능: ferries: 페리 항로toll: 유료 도로motorway: 자동차 전용 도로schoolzone: 어린이 보호 구역uturn: 유턴(기본값: null)여러 개의 제한 옵션을 사용하려면 다음과 같이 연결 (예: [" ferries", "motorway"]) | 선택 |
roadevent | Int | 유고(교통사고, 행사, 재난, 도로 공사 등의 교통 장애)로 인한 도로 통제 정보 반영 옵션0: 도로 전면 통제 정보 반영1: 출발지 및 목적지 주변의 도로 전면 통제 정보 반영 안 함2: 모든 도로 전면 통제 정보 반영 안 함(기본값: 0) | 선택 |
alternatives | Boolean | 대안 경로 제공 여부true: 대안 경로 제공false: 대안 경로 미제공(기본값: false) | 선택 |
road_details | Boolean | 상세 도로 정보 제공 여부true: 상세 도로 정보 제공false: 상세 도로 정보 미제공(기본값: false) | 선택 |
car_type | Int | 차종 (기본값: 1) | 선택 |
car_fuel | String | 차량 유종 정보 다음 중 하나: GASOLINE: 휘발유DIESEL: 경유LPG: LPG(기본값: GASOLINE) | 선택 |
car_hipass | Boolean | 하이패스 장착 여부true: 하이패스 장착false: 하이패스 미장착(기본값: false) | 선택 |
summary | Boolean | 요약 정보만 제공 여부true: 요약 정보 제공false: 요약 정보 미제공(기본값: false) | 선택 |
Response 링크 복사
응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 요청 본문은 JSON포맷으로 전달합니다.
응답 코드 예제 링크 복사
{
"trans_id": "0194de353ee97a56a7807b8a505eb4da",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"summary": {
"origin": {
"name": "",
"x": 127.11023403583478,
"y": 37.39434769502827
},
"destination": {
"name": "",
"x": 127.10859622855493,
"y": 37.40199450213265
},
"waypoints": [
{
"name": "name0",
"x": 127.11341740484119,
"y": 37.39639001677204
}
],
"priority": "RECOMMEND",
"bound": {
"min_x": 127.10873060789754,
"min_y": 37.39446252338457,
"max_x": 127.11400101911747,
"max_y": 37.402458630852735
},
"fare": {
"taxi": 6600,
"toll": 0
},
"distance": 2193,
"duration": 574
},
"sections": [
{
"distance": 1074,
"duration": 280,
"bound": {
"min_x": 127.11341931516797,
"min_y": 37.394469584427156,
"max_x": 127.11406301821938,
"max_y": 37.398332068681995
},
"roads": [
{
"name": "",
"distance": 22,
"duration": 5,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10991634747967,
37.39447145478345,
127.10966790676201,
37.394469584427156
]
},
{
"name": "판교역로",
"distance": 364,
"duration": 97,
"traffic_speed": 27.0,
"traffic_state": 3,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10967141980313,
37.39512739646385,
127.10968100356395,
37.396226781360426,
127.10967417816033,
37.39775855885587
]
},
{
"name": "판교역로192번길",
"distance": 398,
"duration": 113,
"traffic_speed": 23.0,
"traffic_state": 3,
"vertexes": [
127.10967417816033,
37.39775855885587,
127.10991144303469,
37.39775133437272,
127.11030660039278,
37.39776331905757,
127.11058861237368,
37.39779247292587,
127.11190492731849,
37.39822587238842,
127.11217511696259,
37.39829998747621,
127.11242335797999,
37.39831987264784,
127.11275097123547,
37.39831332063064,
127.1130784782746,
37.3983157776669,
127.11404960021814,
37.398332068681995
]
},
{
"name": "",
"distance": 233,
"duration": 39,
"traffic_speed": 42.0,
"traffic_state": 0,
"vertexes": [
127.11404960021814,
37.398332068681995,
127.11403422576758,
37.39771922184463,
127.11406301821938,
37.39623266200683
]
},
{
"name": "대왕판교로606번길",
"distance": 57,
"duration": 26,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11406301821938,
37.39623266200683,
127.11341931516797,
37.39622783738649
]
}
],
"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.10967417816033,
"y": 37.39775855885587,
"distance": 364,
"duration": 97,
"type": 2,
"guidance": "광장로 방면으로 우회전",
"road_index": 2
},
{
"name": "",
"x": 127.11404960021814,
"y": 37.398332068681995,
"distance": 398,
"duration": 113,
"type": 2,
"guidance": "백현동 방면으로 우회전",
"road_index": 3
},
{
"name": "",
"x": 127.11406301821938,
"y": 37.39623266200683,
"distance": 233,
"duration": 39,
"type": 2,
"guidance": "판교테크노밸리 양재 내곡 방면으로 우회전",
"road_index": 4
},
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 57,
"duration": 26,
"type": 1000,
"guidance": "경유지",
"road_index": -1
}
]
},
{
"distance": 1119,
"duration": 294,
"bound": {
"min_x": 127.10863660151416,
"min_y": 37.39622538141045,
"max_x": 127.11341931516797,
"max_y": 37.40242613861426
},
"roads": [
{
"name": "대왕판교로606번길",
"distance": 29,
"duration": 6,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11341931516797,
37.39622783738649,
127.11309181718316,
37.39622538141045
]
},
{
"name": "분당내곡로",
"distance": 392,
"duration": 62,
"traffic_speed": 25.0,
"traffic_state": 3,
"vertexes": [
127.11309181718316,
37.39622538141045,
127.11307829458244,
37.39641450597087,
127.1130803894646,
37.398153598349445,
127.11307964622586,
37.39821666808455,
127.1130784782746,
37.3983157776669,
127.11308594924428,
37.39864022099831,
127.11311303420219,
37.39921711263319,
127.11313041857109,
37.39965877010523,
127.11312925062586,
37.399757879664605
]
},
{
"name": "대왕판교로644번길",
"distance": 124,
"duration": 50,
"traffic_speed": 20.0,
"traffic_state": 3,
"vertexes": [
127.11312925062586,
37.399757879664605,
127.11274420726458,
37.39984509856906,
127.11173886656147,
37.39985557194009
]
},
{
"name": "",
"distance": 559,
"duration": 173,
"traffic_speed": 13.0,
"traffic_state": 2,
"vertexes": [
127.11173886656147,
37.39985557194009,
127.11175987981302,
37.40094603107842,
127.11174254485269,
37.40241465350646,
127.11170855662199,
37.402423408918274,
127.10967543155922,
37.40242613861426,
127.10863660151416,
37.40240029023456
]
},
{
"name": "",
"distance": 15,
"duration": 3,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10863660151416,
37.40240029023456,
127.1086494963113,
37.402265226201656
]
}
],
"guides": [
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 0,
"duration": 0,
"type": 1000,
"guidance": "판교테크노밸리 양재 내곡 방면으로 경유지",
"road_index": 0
},
{
"name": "판교역사거리",
"x": 127.11309181718316,
"y": 37.39622538141045,
"distance": 29,
"duration": 6,
"type": 2,
"guidance": "동판교IC 내곡,서울 방면으로 우회전",
"road_index": 1
},
{
"name": "삼평사거리",
"x": 127.11312925062586,
"y": 37.399757879664605,
"distance": 392,
"duration": 62,
"type": 1,
"guidance": "대왕판교로 경기창조경제혁신센터 방면으로 좌회전",
"road_index": 2
},
{
"name": "",
"x": 127.11173886656147,
"y": 37.39985557194009,
"distance": 124,
"duration": 50,
"type": 2,
"guidance": "우회전",
"road_index": 3
},
{
"name": "",
"x": 127.10863660151416,
"y": 37.40240029023456,
"distance": 559,
"duration": 173,
"type": 1,
"guidance": "좌회전",
"road_index": 4
},
{
"name": "목적지",
"x": 127.1086494963113,
"y": 37.402265226201656,
"distance": 15,
"duration": 3,
"type": 101,
"guidance": "목적지",
"road_index": -1
}
]
}
]
}
]
}
{
"trans_id": "0194de353ee97a56a7807b8a505eb4da",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"summary": {
"origin": {
"name": "",
"x": 127.11023403583478,
"y": 37.39434769502827
},
"destination": {
"name": "",
"x": 127.10859622855493,
"y": 37.40199450213265
},
"waypoints": [
{
"name": "name0",
"x": 127.11341740484119,
"y": 37.39639001677204
}
],
"priority": "RECOMMEND",
"bound": {
"min_x": 127.10873060789754,
"min_y": 37.39446252338457,
"max_x": 127.11400101911747,
"max_y": 37.402458630852735
},
"fare": {
"taxi": 6600,
"toll": 0
},
"distance": 2193,
"duration": 574
},
"sections": [
{
"distance": 1074,
"duration": 280,
"bound": {
"min_x": 127.11341931516797,
"min_y": 37.394469584427156,
"max_x": 127.11406301821938,
"max_y": 37.398332068681995
},
"roads": [
{
"name": "",
"distance": 22,
"duration": 5,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10991634747967,
37.39447145478345,
127.10966790676201,
37.394469584427156
]
},
{
"name": "판교역로",
"distance": 364,
"duration": 97,
"traffic_speed": 27.0,
"traffic_state": 3,
"vertexes": [
127.10966790676201,
37.394469584427156,
127.10967141980313,
37.39512739646385,
127.10968100356395,
37.396226781360426,
127.10967417816033,
37.39775855885587
]
},
{
"name": "판교역로192번길",
"distance": 398,
"duration": 113,
"traffic_speed": 23.0,
"traffic_state": 3,
"vertexes": [
127.10967417816033,
37.39775855885587,
127.10991144303469,
37.39775133437272,
127.11030660039278,
37.39776331905757,
127.11058861237368,
37.39779247292587,
127.11190492731849,
37.39822587238842,
127.11217511696259,
37.39829998747621,
127.11242335797999,
37.39831987264784,
127.11275097123547,
37.39831332063064,
127.1130784782746,
37.3983157776669,
127.11404960021814,
37.398332068681995
]
},
{
"name": "",
"distance": 233,
"duration": 39,
"traffic_speed": 42.0,
"traffic_state": 0,
"vertexes": [
127.11404960021814,
37.398332068681995,
127.11403422576758,
37.39771922184463,
127.11406301821938,
37.39623266200683
]
},
{
"name": "대왕판교로606번길",
"distance": 57,
"duration": 26,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11406301821938,
37.39623266200683,
127.11341931516797,
37.39622783738649
]
}
],
"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.10967417816033,
"y": 37.39775855885587,
"distance": 364,
"duration": 97,
"type": 2,
"guidance": "광장로 방면으로 우회전",
"road_index": 2
},
{
"name": "",
"x": 127.11404960021814,
"y": 37.398332068681995,
"distance": 398,
"duration": 113,
"type": 2,
"guidance": "백현동 방면으로 우회전",
"road_index": 3
},
{
"name": "",
"x": 127.11406301821938,
"y": 37.39623266200683,
"distance": 233,
"duration": 39,
"type": 2,
"guidance": "판교테크노밸리 양재 내곡 방면으로 우회전",
"road_index": 4
},
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 57,
"duration": 26,
"type": 1000,
"guidance": "경유지",
"road_index": -1
}
]
},
{
"distance": 1119,
"duration": 294,
"bound": {
"min_x": 127.10863660151416,
"min_y": 37.39622538141045,
"max_x": 127.11341931516797,
"max_y": 37.40242613861426
},
"roads": [
{
"name": "대왕판교로606번길",
"distance": 29,
"duration": 6,
"traffic_speed": 17.0,
"traffic_state": 2,
"vertexes": [
127.11341931516797,
37.39622783738649,
127.11309181718316,
37.39622538141045
]
},
{
"name": "분당내곡로",
"distance": 392,
"duration": 62,
"traffic_speed": 25.0,
"traffic_state": 3,
"vertexes": [
127.11309181718316,
37.39622538141045,
127.11307829458244,
37.39641450597087,
127.1130803894646,
37.398153598349445,
127.11307964622586,
37.39821666808455,
127.1130784782746,
37.3983157776669,
127.11308594924428,
37.39864022099831,
127.11311303420219,
37.39921711263319,
127.11313041857109,
37.39965877010523,
127.11312925062586,
37.399757879664605
]
},
{
"name": "대왕판교로644번길",
"distance": 124,
"duration": 50,
"traffic_speed": 20.0,
"traffic_state": 3,
"vertexes": [
127.11312925062586,
37.399757879664605,
127.11274420726458,
37.39984509856906,
127.11173886656147,
37.39985557194009
]
},
{
"name": "",
"distance": 559,
"duration": 173,
"traffic_speed": 13.0,
"traffic_state": 2,
"vertexes": [
127.11173886656147,
37.39985557194009,
127.11175987981302,
37.40094603107842,
127.11174254485269,
37.40241465350646,
127.11170855662199,
37.402423408918274,
127.10967543155922,
37.40242613861426,
127.10863660151416,
37.40240029023456
]
},
{
"name": "",
"distance": 15,
"duration": 3,
"traffic_speed": 16.0,
"traffic_state": 0,
"vertexes": [
127.10863660151416,
37.40240029023456,
127.1086494963113,
37.402265226201656
]
}
],
"guides": [
{
"name": "경유지",
"x": 127.11341931516797,
"y": 37.39622783738649,
"distance": 0,
"duration": 0,
"type": 1000,
"guidance": "판교테크노밸리 양재 내곡 방면으로 경유지",
"road_index": 0
},
{
"name": "판교역사거리",
"x": 127.11309181718316,
"y": 37.39622538141045,
"distance": 29,
"duration": 6,
"type": 2,
"guidance": "동판교IC 내곡,서울 방면으로 우회전",
"road_index": 1
},
{
"name": "삼평사거리",
"x": 127.11312925062586,
"y": 37.399757879664605,
"distance": 392,
"duration": 62,
"type": 1,
"guidance": "대왕판교로 경기창조경제혁신센터 방면으로 좌회전",
"road_index": 2
},
{
"name": "",
"x": 127.11173886656147,
"y": 37.39985557194009,
"distance": 124,
"duration": 50,
"type": 2,
"guidance": "우회전",
"road_index": 3
},
{
"name": "",
"x": 127.10863660151416,
"y": 37.40240029023456,
"distance": 559,
"duration": 173,
"type": 1,
"guidance": "좌회전",
"road_index": 4
},
{
"name": "목적지",
"x": 127.1086494963113,
"y": 37.402265226201656,
"distance": 15,
"duration": 3,
"type": 101,
"guidance": "목적지",
"road_index": -1
}
]
}
]
}
]
}
코드가 숨겨졌습니다.
요청 응답에 대한 객체 정보는 다음과 같습니다.
표 4
응답 객체
| 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 좌표(위도) | 필수 |
waypoints | Object[] | 경유지 정보 | 필수 |
name | String | 경유지 이름 | 필수 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
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 | 현재 가이드에 대한 링크 인덱스 | 필수 |