다크 모드
다중 출발・목적지(Matrix) 길찾기
한 개 이상의 출발지에서 한 개 이상의 목적지까지의 경로의 요약 정보를 제공합니다. 출발지와 목적지는 각각 최대 200개까지 설정할 수 있습니다.
DANGER
Request
요청 호출 방식과 각 요청 헤더에 포함될 내용을 안내합니다. 요청이 실패할 경우 문제 해결하기에서 에러에 대한 상세 내용을 확인하세요.
호출 방식
| Method | URL |
|---|---|
POST | https://apis-navi.kakaomobility.com/affiliate/v1/matrix/directions |
요청 헤더(Header)
| Parameter | Description |
|---|---|
| Authorization | KakaoAK ${REST_API_KEY} {REST_API_KEY}: 카카오디벨로퍼스에서 발급 받은 REST API 키 |
| Content-Type | application/json |
요청 코드 예제
bash
curl -v -X POST "http://sandbox-navi-api.kakao.com/affiliate/v1/matrix/directions" \
-H "Content-Type: application/json" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \ // 카카오디벨로퍼스에서 발급 받은 API 키 값
-d '{
"priority": "TIME",
"avoid": null,
"radius": 10000,
"origins": [
{
"key": "0",
"x": 127.10944211462966,
"y": 37.32663448680758
},
{
"key": "1",
"x": 127.05971101787819,
"y": 37.31883381417869
},
{
"key": "2",
"x": 127.06908737313162,
"y": 37.31420428563164
}
],
"destinations": [
{
"key": "0",
"x": 127.11082432539847,
"y": 37.32615829528716
},
{
"key": "1",
"x": 127.0597521023936,
"y": 37.319158530933635
}
]
}'요청에 대한 파라미터는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
origins | Object | 출발지. 최대 200까지 허용 | 필수 |
key | String | 각 출발지를 구분하기 위한 임의의 문자열 지정 | 필수 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
destinations | Object[] | 목적지. 최대 200까지 허용 | 필수 |
key | String | 각 목적지를 구분하기 위한 임의의 문자열 지정 | 필수 |
x | Double | X 좌표(경도) | 필수 |
y | Double | Y 좌표(위도) | 필수 |
radius | Int | 길찾기 반경(미터)(최대: 20000) | 필수 |
priority | String | 경로 탐색 우선순위 옵션 다음 중 하나: TIME: 최단 시간DISTANCE: 최단 경로NO_TRAFFIC_INFO: 실시간 교통정보를 반영하지 않은 가장 빠른 경로(기본값: TIME) | 선택 |
avoid | String[] | 경로 탐색 제한 옵션 다음 값 사용 가능: ferries: 페리 항로toll: 유료 도로motorway: 자동차 전용 도로schoolzone: 어린이 보호 구역uturn: 유턴(기본값: null)여러 개의 제한 옵션을 사용하려면 다음과 같이 연결 (예: [" ferries", "motorway"]) | 선택 |
roadevent | Int | 유고(교통사고, 행사, 재난, 도로 공사 등의 교통 장애)로 인한 도로 통제 정보 반영 옵션0: 도로 전면 통제 정보 반영1: 출발지 및 목적지 주변의 도로 전면 통제 정보 반영 안 함2: 모든 도로 전면 통제 정보 반영 안 함(기본값: 0) | 선택 |
Response
응답 성공 시 요청에 대한 성공 여부를 HTTP 상태 코드로, 요청 본문은 JSON 포맷으로 전달합니다.
응답 코드 예제
bash
{
"trans_id": "ae98ef77f0824abe90d651c622742f4a",
"routes": [
{
"result_code": 0,
"result_msg": "길찾기 성공",
"origin_key": "0",
"destination_key": "0",
"summary": {
"distance": 3053,
"duration": 885
}
},
{
"result_code": 0,
"result_msg": "길찾기 성공",
"origin_key": "0",
"destination_key": "1",
"summary": {
"distance": 6540,
"duration": 1437
}
},
{
"result_code": 0,
"result_msg": "길찾기 성공",
"origin_key": "1",
"destination_key": "0",
"summary": {
"distance": 8484,
"duration": 2217
}
},
{
"result_code": 0,
"result_msg": "길찾기 성공",
"origin_key": "1",
"destination_key": "1",
"summary": {
"distance": 105,
"duration": 22
}
},
{
"result_code": 0,
"result_msg": "길찾기 성공",
"origin_key": "2",
"destination_key": "0",
"summary": {
"distance": 9015,
"duration": 2028
}
},
{
"result_code": 0,
"result_msg": "길찾기 성공",
"origin_key": "2",
"destination_key": "1",
"summary": {
"distance": 1382,
"duration": 358
}
}
]
}요청 응답에 대한 객체 정보는 다음과 같습니다.
| Name | Type | Description | Required |
|---|---|---|---|
trans_id | String | 경로 요청 ID | 필수 |
routes | Object[] | 경로 정보, 경로 수만큼 생성 | 필수 |
result_code | Int | 경로 탐색 결과 코드 | 필수 |
result_msg | String | 경로 탐색 결과 메시지 | 필수 |
origin_key | String | origins의 key 값으로 지정한 각 출발지의 키 값 | 필수 |
destination_key | String | destinations의 key 값으로 지정한 각 목적지의 키 값 | 필수 |
summary | Object | 경로 요약 정보 | 필수 |
distance | Int | 전체 검색 결과 거리(미터) | 필수 |
duration | Int | 목적지까지 소요 시간(초) | 필수 |