이 가이드의 대상: 트럭 또는 기타 대형 차량을 사용하여 여행 계획 및 실행을 위한 서비스를 빌드하는 개발자라면 이 가이드를 읽어보세요. 관련 사용 사례로는 이동 시간 및 거리 계산, 도착 예정 시간(ETA) 계산, 내비게이션 애플리케이션에서 사용할 경로 생성 등이 있습니다.
이 가이드에서 다루는 내용: 이 가이드에서는 Routes API와 대형 차량 경로 안내를 함께 사용하여 상업용 트럭 또는 여객 버스와 같은 대형 차량의 특정 속성을 고려하는 경로, 이동 거리, 예상 이동 시간, ETA를 요청하는 방법을 설명합니다.
Route Optimization API를 사용하여 대형 차량의 차량 관리 수준 계산을 실행하는 방법에 관한 자세한 내용은 Route Optimization 트럭 경로 안내 문서를 참고하세요.
학습할 내용
다음 작업을 실행하는 방법을 알아봅니다.
- 유효한 경로 안내 요청을 구성합니다.
- 크기, 무게, 기타 특성을 사용하여 실제 차량의 차량 정보를 지정합니다.
- 경로 토큰 및 이동 안전 플래그를 포함한 응답을 해석합니다.
기본 요건
- Google Cloud 프로젝트를 만들고 Routes API 를 사용 설정해야 합니다.
- 프로젝트가 대형 차량 경로 안내를 위해 프로비저닝 되어야 합니다. 대형 차량 경로 안내는 일부 고객에게만 제공됩니다. 액세스를 요청하려면 Google에 문의하세요.
제한사항
시작하기 전에 다음 제한사항 및 요구사항을 숙지해야 합니다.
- 지리적 가용성: 대형 차량 경로 안내는 미국 본토 48개 주 (정식 버전) 및 일본 (실험용)에서 사용할 수 있습니다. 알래스카, 하와이, 미국령에서는 사용할 수 없습니다.
- 운전자 권고 및 안전. 운전자는 이 API에서 반환된 경로가 안전하거나 합법적이라고 전적으로 신뢰해서는 안 됩니다. 경로가 차량에 적합하다고 보장되지 않으며, 경로를 따를 경우 운전자가 낮은 다리 또는 대형 차량이 금지된 도로와 같은 위험에 노출될 수 있습니다.
- 최선의 노력 경로. 경우에 따라 API에서 이동 제한사항을 완전히 준수하는 경로를 찾을 수 없습니다. 대신 제한된 지역을 여전히 통과할 수 있는 '최선의 노력' 경로를 반환합니다. Routes API 응답은
routeRestrictionsPartiallyIgnored필드에서 이러한 경로에 명확하게 플래그를 지정합니다. 이러한 경우 다른 소스 데이터를 사용하여 경로를 신중하게 계획하세요. 플래그가 지정된 경로를 계획 또는 내비게이션의 단일 정보 소스로 사용하지 마세요. - 지원되지 않는 기능: 대형 차량 경로 안내는 다음을 지원하지 않습니다.
다음:
- 트럭 통행료
- 제한 속도
- 방사성 유해 물질 경로 안내
- 사용량 한도: 모든 요청에는 표준 초당 쿼리 수 (QPS) 한도가 적용됩니다.
트럭 경로 요청 빌드
트럭 경로를 가져오려면 차량을 설명하는 특정 매개변수가 포함된 HTTPS 요청을 Routes API 엔드포인트로 보냅니다. 이 섹션의 개념은 단일 경로 요청과 경로 행렬 요청 모두에 적용됩니다.
엔드포인트
트럭 경로 안내에는 두 가지 엔드포인트를 사용할 수 있습니다.
computeRoutes: 한 출발지와 한 도착지 간의 단일 경로를 계산합니다.computeRouteMatrix: 출발지 및 도착지 행렬의 거리와 시간을 계산하지만 경로 다중선은 반환하지 않습니다.
주요 요청 매개변수
요청 본문에 다음 매개변수를 포함하여 트럭 경로 안내를 사용 설정해야 합니다.
travelMode: 이 값을TRUCK으로 설정합니다.routingPreference: 이 값을TRAFFIC_AWARE_OPTIMAL로 설정합니다.routeModifiers: 이 객체에는 차량의 속성을 정의하는vehicleInfo객체가 포함되어 있습니다.vehicleInfo객체는 아래에 자세히 설명되어 있습니다.
차량 속성 지정
요청을 보내려면 차량을 설명하는 vehicleInfo 객체가 포함된 요청 본문을 제공해야 합니다. 이 정보를 실제 차량의 물리적 세부정보와 일치하는 사양으로 생각하세요. 서비스는 차량의 속성을 기반으로 도로 제한사항을 고려하는 경로를 반환하기 위해 이러한 세부정보를 요구합니다.
차량 측정
필드 이름에 표시된 대로 차량 무게를 킬로그램으로, 차량 크기를 밀리미터로 제공합니다. 예를 들어 총 높이는 밀리미터 (totalHeightMm)로 제공해야 합니다. 트럭 크기는 피트 또는 미터로 표현되는 경우가 많으므로 단위 변환이 필요할 수 있습니다.
영국식 단위에서 미터법으로 변환
영국식 단위에서 변환할 때는 항상 표준 도로 및 지하도 크기 제한사항과 함께 특정 차량 크기를 고려하세요. 이는 분수 값에서 특히 중요할 수 있습니다. 실제 차량의 크기에 따라 분수 값을 반올림하면 차량의 경로 안내가 지나치게 제한될 수 있습니다.
예를 들면 다음과 같습니다.
- 너비: 미국 트레일러의 너비는 8피트 6인치인 경우가 많으며 이는 2,590.8mm로 변환됩니다. 2,591mm로 반올림하면 차량이 8피트 6인치보다 크다는 것을 나타내므로 미국 도로에서 대형 차량으로 분류됩니다. 그러면 의도한 것과 의미가 다른 제약 조건에 따라 계산된 경로가 생성됩니다.
- 높이: 높이가 13.5피트인 일반적인 트랙터 트레일러에는 11피트 다리 아래로 이어지는 경로가 적합하지 않습니다. 하지만 약 10피트의 소형 박스 트럭은 지하도를 탐색할 수 있습니다. 따라서 차량 속성을 정확하게 지정하는 것이 중요합니다.
다음은 vehicleInfo 객체의 예를 보여주는 코드 스니펫입니다.
"vehicleInfo": {
"totalAxleCount": 5,
"totalHeightMm": 4114,
"totalLengthMm": 21945,
"totalWidthMm": 2590,
"totalWeightKg": 32658,
"trailerInfo": [{
"lengthMm": 16154
}
vehicleInfo 객체 필드
다음 표는 요청과 함께 보낼 수 있는 모든 차량 및 하중 정의를 보여줍니다.
| 필드 | 설명 | 참고 / 값 |
|---|---|---|
totalHeightMm
|
차량의 최대 높이입니다. | 밀리미터 단위로 반내림됩니다. 반올림에 관한 자세한 내용은 영국식 단위에서 미터법으로 변환을 참고하세요. |
totalWidthMm
|
차량의 최대 너비입니다. | 밀리미터 단위로 반내림됩니다. |
totalLengthMm
|
차량과 트레일러의 총 결합 길이입니다. | 밀리미터 단위로 반내림됩니다. |
totalWeightKg
|
총 차량 무게 (트레일러 및 하중 포함)입니다. | 킬로그램 단위로 반내림됩니다. |
totalAxleCount
|
차량과 트레일러의 총 차축 수입니다. | 정확합니다. |
trailerInfo (선택사항)
|
객체 배열로, 트레일러마다 하나씩 있습니다. | 박스 트럭과 같이 트레일러가 없는 차량의 경우 생략합니다. |
hazardousGoodsTypes (선택사항)
|
차량에 있는 유해 물질을 지정하는 배열입니다. | EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER |
필드 마스크 사용
최상의 결과를 얻으려면 요청에 X-Goog-FieldMask 헤더를 포함하여 응답에 원하는 필드를 정확하게 지정하세요. 필드 마스크는 지연 시간을 줄이고 중요한 권고 필드를 수신하도록 합니다. 경로에 차량에 적용되는 제한사항이 하나 이상 있는지 여부를 나타내므로 필드 마스크에 항상 routes.travelAdvisory.routeRestrictionsPartiallyIgnored를 포함하세요.
Routes API의 FieldMask에 관한 자세한 내용은 이 문서를 참고하세요.
유료도로
무료 도로를 선호하려면 요청의 routeModifiers 속성에 avoidTolls를 지정하세요. 경로 수정자에 관한 자세한 내용은
피할 경로 기능 지정을 참고하세요.
avoidTolls를 지정해도 응답에 무료 도로가 보장되지는 않습니다. 경우에 따라 출발지와 도착지 간을 이동하려면 유료 도로를 사용해야 합니다. Routes API 요청의 필드 마스크에 routes.warnings를 포함하면 유료 도로가 포함된 경로는 이 필드 내에서 적절하게 주석 처리됩니다.
기타 경로 안내 동작
travelMode를 TRUCK으로 설정하면 API가 대형 차량의 기동성을 위해 경로를 자동으로 최적화합니다. 생성된 경로는 유턴을 피하고 작은 도로보다 주간선 도로와 고속도로를 선호합니다. 이러한 동작을 사용 설정하기 위해 추가 매개변수 또는 수정자를 설정할 필요는 없습니다.
computeRoutes로 단일 경로 계산
computeRoutes 엔드포인트를 사용하여 한 출발지와 한 도착지 간의 트럭 전용 경로를 계산합니다.
computeRoutes 요청 예
다음은 일반적인 세미 트레일러 트럭의 전체 curl 요청입니다. 이 예에는 엔드포인트, 헤더, 요청 본문이 포함되어 있습니다.
curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
"origin": {
"location": {
"latLng": {
"latitude": 40.883274,
"longitude": -74.704574
}
}
},
"destination": {
"location": {
"latLng": {
"latitude": 40.991920,
"longitude": -75.183371
}
}
},
"travelMode": "TRUCK",
"routingPreference": "TRAFFIC_AWARE_OPTIMAL",
"routeModifiers": {
"vehicleInfo": {
"totalAxleCount": 5,
"totalHeightMm": 4114,
"totalLengthMm": 21945,
"totalWidthMm": 2590,
"totalWeightKg": 32658,
"trailerInfo": [{
"lengthMm": 16154
}]
}
}
}'
computeRoutes 응답 예
다음은 위에 표시된 이전 요청의 응답 예입니다. travelAdvisory 객체에는 routeRestrictionsPartiallyIgnored 플래그가 포함되어 있지 않습니다. 이는 경로에 플래그가 지정되지 않았으며 차량의 속성을 완전히 준수하는 것으로 간주됨을 나타냅니다.
{
"routes": [
{
"distanceMeters": 3426,
"duration": "312s",
"travelAdvisory": {},
"routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
}
]
}
computeRoutes 응답 해석
computeRoutes 엔드포인트에 대한 요청이 성공하면 가능한 경로가 하나 이상 포함된 JSON 응답 객체가 반환됩니다.
주요 응답 필드
- 인코딩된 경로 도형:
routes.polyline. 지도의 경로를 렌더링하는 데 사용할 수 있습니다. - 예상 이동 시간:
routes.duration(초)입니다. 대형 차량 경로 안내 이동 시간은 도로망에서 실제 트럭의 관찰된 이동 속도를 기반으로 학습된 새로운 모델을 사용합니다. 예상 출발 시간에 예상 이동 시간을 더하여 ETA를 계산하는 데 사용할 수도 있습니다. - 경로의 총 거리:
routes.distanceMeters(미터)입니다. - 경로 토큰:
routes.routeToken입니다. 이는 정확하게 계산된 경로를 나타내는 비공개 토큰입니다. 운전자에게 동일한 트럭 전용 경로가 표시되도록 하려면 이 토큰을 Navigation SDK에 전달합니다. 자세한 내용은 Android 또는 iOS용 Navigation SDK 가이드를 참고하세요.
경로 안전 플래그 확인
응답을 받으면 가장 먼저 경로 안전 플래그를 확인해야 합니다. 제공된 경로에 차량에 적합하지 않은 제한사항이 하나 이상 포함되어 있으면 travelAdvisory.routeRestrictionsPartiallyIgnored 필드가 true로 설정됩니다.
이 필드는 '이 경로에 잠재적인 문제가 있어 플래그가 지정되었나요?'라는 질문에 답하는 플래그 역할을 합니다.
false(또는 응답에서 생략됨): 경로에 플래그가 지정되지 않았습니다. 시스템에서 요청에 제공한 매개변수를 완전히 준수 하는 것으로 간주되는 경로를 찾았습니다.true: 경로에 플래그가 지정되었습니다. 시스템에서 완전히 준수하는 경로를 찾을 수 없어 안전하지 않거나 합법적이지 않을 수 있는 '최선의 노력' 경로를 반환했습니다. 이 경로는 매우 신중하게 사용해야 합니다.
경로 행렬 계산 (computeRouteMatrix)
computeRouteMatrix 엔드포인트를 사용하여 여러 출발지와 도착지 간의 이동 시간과 거리를 효율적으로 비교합니다. 예를 들어 새 픽업 위치에 가장 가까운 트럭을 찾는 데 사용할 수 있습니다. 목적에 사용할 차량 출발지를 식별한 후에는 제안된 차량의 경로 세부정보와 경로 토큰을 가져오기 위해 computeRoutes 요청을 실행할 수 있습니다.
computeRouteMatrix를 사용하려면 요청의 루트가 아닌 각 origin 객체 내에서 vehicleInfo를 지정합니다.
computeRouteMatrix 요청 예
{
"origins": [
{
"waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
"routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
},
{
"waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
"routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
}
],
"destinations": [
{ "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
{ "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
],
"travelMode": "TRUCK",
"routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}
computeRouteMatrix 응답 예
응답은 각 객체에 하나의 출발지-도착지 쌍의 시간과 distanceMeters가 포함된 배열입니다.
[
{
"originIndex": 0,
"destinationIndex": 1,
"status": {},
"distanceMeters": 392372,
"duration": "14037s",
"condition": "ROUTE_EXISTS"
},
{ ... }
]
다음 단계
- 세부 경로 안내 내비게이션 제공:
routeToken에서 Android 또는 iOS용 Navigation SDK를 사용하는 방법을 알아봅니다. - 차량 관리 수준 최적화 실행: 대형 차량 경로 안내와 함께 Route Optimization API를 사용합니다.
- API 참조: 가능한 모든 필드 및 값의 전체 목록은 Routes API 참조를 확인하세요.