이 가이드의 대상: 트럭이나 기타 대형 차량을 사용하여 여행 계획 및 실행을 위한 서비스를 빌드하는 개발자라면 이 가이드를 읽어보세요. 관련 사용 사례에는 이동 시간 및 거리 계산, 예상 도착 시간 계산, 내비게이션 애플리케이션에서 사용할 경로 생성이 포함됩니다.
이 가이드에서 다루는 내용: 이 가이드에서는 Routes API를 대형 차량 경로와 함께 사용하여 상용 트럭이나 승객 버스와 같은 대형 차량의 특정 속성을 고려한 경로, 이동 거리, 예상 이동 시간, 도착예정시간을 요청하는 방법을 설명합니다.
Route Optimization API를 사용하여 대형 차량의 차량 수준 계산을 수행하는 방법에 관한 자세한 내용은 Route Optimization 트럭 경로 문서를 참고하세요.
학습할 내용
다음을 실행하는 방법을 알아봅니다.
- 유효한 라우팅 요청을 구성합니다.
- 크기, 무게, 기타 특성을 사용하여 실제 차량의 차량 정보를 지정합니다.
- 경로 토큰 및 이동 안전 플래그를 포함한 응답을 해석합니다.
기본 요건
- Google Cloud 프로젝트를 만들고 Routes API를 사용 설정해야 합니다.
- 프로젝트가 대형 차량 경로를 위해 프로비저닝되어야 합니다. 대형 차량 경로는 제한된 고객 집합에 제공되며 액세스를 요청하려면 Google에 문의하세요.
제한사항
시작하기 전에 다음 제한사항과 요구사항을 숙지해야 합니다.
- 지역별 사용 가능 여부: 대형 차량 경로는 미국 본토 48개 주 (정식 버전) 및 일본(실험용)에서 사용할 수 있습니다. 알래스카, 하와이, 미국령에서는 사용할 수 없습니다.
- 운전자 권고 및 안전. 운전자는 이 API에서 반환하는 경로가 안전하거나 합법적이라고 전적으로 신뢰해서는 안 됩니다. 경로가 차량에 적합하다고 보장할 수 없으며, 경로를 따르면 운전자가 낮은 다리나 대형 차량이 금지된 도로와 같은 위험에 노출될 수 있습니다.
- 최선의 경로. 경우에 따라 API가 이동 제한을 완전히 준수하는 경로를 찾지 못할 수 있습니다. 대신 제한 구역을 통과할 수 있는 '최선의' 경로를 반환합니다. Routes API 응답은
routeRestrictionsPartiallyIgnored필드에서 이러한 경로를 명확하게 표시합니다. 이러한 경우 다른 소스 데이터를 사용하여 경로를 신중하게 계획하세요. 신고된 경로를 계획 또는 탐색을 위한 단일 정보 소스로 사용하지 마세요. - 지원되지 않는 기능: 대형 차량 경로는 다음을 지원하지 않습니다.
- 트럭 통행료
- 제한 속도
- 방사성 유해 물질 경로
- 사용량 한도: 모든 요청에는 표준 초당 쿼리 수(QPS) 한도가 적용됩니다.
트럭 경로 요청 빌드
트럭 경로를 가져오려면 차량을 설명하는 특정 매개변수와 함께 Routes API 엔드포인트에 HTTPS 요청을 보냅니다. 이 섹션의 개념은 단일 경로 및 경로 매트릭스 요청 모두에 적용됩니다.
엔드포인트
트럭 경로에 두 개의 엔드포인트를 사용할 수 있습니다.
computeRoutes: 출발지 1개와 목적지 1개 사이의 단일 경로를 계산합니다.computeRouteMatrix: 출발지와 목적지 행렬의 거리와 소요 시간을 계산하지만 경로 다중선은 반환하지 않습니다.
주요 요청 매개변수
요청 본문에 다음 매개변수를 포함하여 트럭 경로를 사용 설정해야 합니다.
travelMode: 이 값을TRUCK로 설정합니다.routingPreference: 이 값을TRAFFIC_AWARE_OPTIMAL로 설정합니다.routeModifiers: 이 객체에는 차량의 속성을 정의하는vehicleInfo객체가 포함됩니다.vehicleInfo객체는 아래에서 자세히 설명합니다.
차량 속성 지정
요청을 보내려면 차량을 설명하는 vehicleInfo 객체가 포함된 요청 본문을 제공해야 합니다. 이 정보는 실제 차량의 물리적 세부정보와 일치하는 사양이라고 생각하면 됩니다. 서비스는 차량 속성에 따라 도로 제한을 고려하는 경로를 반환하기 위해 이러한 세부정보가 필요합니다.
차량 측정값
필드 이름에 표시된 대로 차량 무게(킬로그램)와 차량 크기(밀리미터)를 제공합니다. 예를 들어 총 높이는 밀리미터 (totalHeightMm)로 제공해야 합니다. 트럭 크기는 피트 또는 미터로 표시되는 경우가 많으므로 단위 변환이 필요할 수 있습니다.
야드파운드법에서 미터법으로 변환
야드파운드법 단위에서 변환할 때는 항상 표준 도로 및 지하도 크기 제한과 함께 특정 차량 크기를 고려하세요. 이는 특히 소수 값에서 중요할 수 있습니다. 실제 차량의 크기에 따라 소수점 값을 반올림하면 차량에 지나치게 제한적인 경로가 생성될 수 있습니다.
예를 들면 다음과 같습니다.
- 너비: 많은 미국 트레일러의 너비는 8' 6"이며, 이는 2,590.8mm로 변환됩니다. 2,591mm로 반올림하면 차량이 8피트 6인치보다 크다는 의미이므로 미국 도로에서 대형 차량으로 분류됩니다. 그러면 의도한 것과 의미 있게 다른 제약조건에 따라 계산된 경로가 생성됩니다.
- 높이: 높이가 11피트인 다리 아래로 이어지는 경로는 높이가 13.5피트인 일반적인 트랙터 트레일러에 적합하지 않습니다. 하지만 약 3m 크기의 소형 박스 트럭은 지하도를 통과할 수 있습니다. 따라서 차량 속성을 정확하게 지정하는 것이 중요합니다.
다음은 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의 FieldMasks에 관한 자세한 내용은 이 도움말을 참고하세요.
유료도로
무료 경로를 선호하려면 요청의 routeModifiers 속성에 avoidTolls를 지정합니다. 경로 수정자에 관한 자세한 내용은 피해야 할 경로 기능 지정을 참고하세요.
avoidTolls를 지정해도 응답에 무료 경로가 보장되지는 않습니다. 경우에 따라 출발지와 목적지 사이를 이동하려면 유료 도로를 이용해야 합니다. Routes API 요청의 필드 마스크에 routes.warnings를 포함하면 유료 도로가 포함된 경로에 이 필드 내에 주석이 추가됩니다.
기타 라우팅 동작
travelMode를 TRUCK로 설정하면 API가 대형 차량의 기동성에 맞게 경로를 자동으로 최적화합니다. 생성된 경로는 유턴을 피하고 작은 도로보다 주간 고속도로와 고속도로를 선호합니다. 이러한 동작을 사용 설정하기 위해 추가 매개변수나 수정자를 설정할 필요는 없습니다.
computeRoutes를 사용하여 단일 경로 계산
computeRoutes 엔드포인트를 사용하여 출발지 1곳과 목적지 1곳 간의 트럭 전용 경로를 계산합니다.
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"
},
{ ... }
]
다음 단계
- 세부 경로 안내 내비게이션 제공: Android 또는 iOS용 Navigation SDK에서
routeToken를 사용하는 방법을 알아보세요. - 차량 수준 최적화 수행: 대형 차량 라우팅과 함께 Route Optimization API를 사용합니다.
- API 참조: 가능한 모든 필드와 값의 전체 목록은 Routes API 참조를 확인하세요.