Đối tượng của hướng dẫn này: Hãy đọc hướng dẫn này nếu bạn là nhà phát triển xây dựng dịch vụ lập kế hoạch và thực hiện chuyến đi bằng xe tải hoặc các phương tiện lớn khác. Các trường hợp sử dụng có liên quan bao gồm tính toán thời gian di chuyển và khoảng cách, tính toán Giờ đến dự kiến hoặc tạo tuyến đường mà ứng dụng chỉ đường sẽ sử dụng.
Nội dung hướng dẫn: Hướng dẫn này trình bày cách sử dụng Routes API với tính năng Định tuyến xe lớn để yêu cầu tuyến đường, quãng đường di chuyển, thời gian di chuyển dự kiến và thời gian đến dự kiến (ETA) có tính đến các thuộc tính cụ thể của xe lớn, chẳng hạn như xe tải thương mại hoặc xe buýt chở khách.
Để biết thông tin về cách thực hiện các phép tính ở cấp đội xe cho xe lớn bằng Route Optimization API, hãy xem Tài liệu về định tuyến xe tải bằng Route Optimization.
Kiến thức bạn sẽ học được
Bạn sẽ tìm hiểu cách thực hiện những việc sau:
- Tạo một yêu cầu định tuyến hợp lệ.
- Chỉ định thông tin về xe cho xe thực tế của bạn, sử dụng kích thước, trọng lượng và các đặc điểm khác.
- Diễn giải phản hồi, bao gồm cả mã thông báo tuyến đường và cờ an toàn khi di chuyển.
Điều kiện tiên quyết
- Bạn phải tạo dự án trên đám mây của Google Cloud và bật Routes API.
- Dự án của bạn phải được cấp phép sử dụng tính năng Định tuyến xe lớn. Tính năng định tuyến cho xe lớn chỉ được cung cấp cho một số khách hàng, hãy liên hệ với chúng tôi để yêu cầu quyền truy cập
Các điểm hạn chế
Trước khi bắt đầu, bạn phải nắm được các yêu cầu và hạn chế sau đây.
- Phạm vi cung cấp theo khu vực địa lý: Tính năng định tuyến cho xe lớn hiện có ở 48 tiểu bang tiếp giáp của Hoa Kỳ (Giai đoạn phát hành rộng rãi) và Nhật Bản (Thử nghiệm). Dịch vụ này không được cung cấp ở Alaska, Hawaii hoặc các lãnh thổ thuộc Hoa Kỳ.
- An toàn và tư vấn cho tài xế. Tài xế không được chỉ dựa vào các tuyến đường do API này trả về để đảm bảo an toàn hoặc hợp pháp. Các tuyến đường không được đảm bảo là phù hợp với xe và việc đi theo các tuyến đường đó có thể khiến người lái xe gặp phải các mối nguy hiểm như cầu thấp hoặc đường cấm xe lớn.
- Tuyến đường tốt nhất có thể. Trong một số trường hợp, API không thể tìm thấy tuyến đường
tuân thủ đầy đủ các quy định hạn chế về việc đi lại. Thay vào đó, API này sẽ trả về tuyến đường "tốt nhất có thể" và tuyến đường này vẫn có thể đi qua các khu vực bị hạn chế. Phản hồi của Routes API gắn cờ rõ ràng cho các tuyến đường này trong trường
routeRestrictionsPartiallyIgnored. Hãy lên kế hoạch cho tuyến đường của bạn một cách cẩn thận trong những trường hợp này, tốt nhất là sử dụng dữ liệu nguồn khác. Đừng sử dụng tuyến đường bị gắn cờ làm nguồn đáng tin cậy duy nhất để lập kế hoạch hoặc đi theo chỉ dẫn. - Tính năng không được hỗ trợ: Tính năng định tuyến cho xe lớn không hỗ trợ những tính năng sau:
- Phí cầu đường cho xe tải
- Giới hạn tốc độ
- Tuyến đường cho vật liệu nguy hiểm phóng xạ
- Hạn mức sử dụng: Tất cả yêu cầu đều phải tuân theo hạn mức số yêu cầu mỗi giây (QPS) tiêu chuẩn.
Tạo yêu cầu về tuyến đường cho xe tải
Để nhận tuyến đường cho xe tải, bạn gửi một yêu cầu HTTPS đến điểm cuối của Routes API bằng các tham số cụ thể mô tả xe của bạn. Các khái niệm trong phần này áp dụng cho cả yêu cầu về một tuyến đường và yêu cầu về ma trận tuyến đường.
Điểm cuối
Bạn có thể sử dụng hai điểm cuối để định tuyến xe tải:
computeRoutes: Tính toán một tuyến đường duy nhất giữa một điểm xuất phát và một điểm đến.computeRouteMatrix: Tính khoảng cách và thời gian cho một ma trận điểm xuất phát và điểm đến, nhưng không trả về hình nhiều đường của tuyến đường.
Các tham số chính của yêu cầu
Trong phần nội dung yêu cầu, bạn phải thêm các tham số sau để bật tính năng định tuyến xe tải:
travelMode: Đặt giá trị này thànhTRUCK.routingPreference: Đặt giá trị này thànhTRAFFIC_AWARE_OPTIMAL.routeModifiers: Đối tượng này chứa đối tượngvehicleInfo, nơi bạn xác định các thuộc tính của xe. Đối tượngvehicleInfođược mô tả chi tiết bên dưới.
Chỉ định thuộc tính xe
Để gửi yêu cầu, bạn phải cung cấp nội dung yêu cầu có đối tượng vehicleInfo mô tả xe của bạn. Hãy coi thông tin này là thông số kỹ thuật
phù hợp với thông tin chi tiết thực tế về chiếc xe của bạn. Dịch vụ này yêu cầu những thông tin chi tiết này để trả về các tuyến đường có tính đến các quy định hạn chế về đường dựa trên các thuộc tính của xe.
Số đo xe
Cung cấp trọng lượng xe tính bằng kilôgam và kích thước xe tính bằng milimét, như được chỉ định trong tên trường. Ví dụ: tổng chiều cao phải được cung cấp bằng milimét (totalHeightMm). Vì kích thước xe tải thường được biểu thị bằng feet hoặc mét, nên bạn có thể cần phải chuyển đổi đơn vị.
Chuyển đổi từ hệ đo lường Anh sang hệ mét
Khi chuyển đổi từ hệ đo lường Anh, hãy luôn xem xét kích thước cụ thể của xe cùng với giới hạn kích thước tiêu chuẩn của đường và đường hầm. Điều này có thể đặc biệt quan trọng đối với các giá trị phân số. Tuỳ thuộc vào kích thước thực tế của xe, việc làm tròn giá trị phân số có thể dẫn đến việc định tuyến quá hạn chế cho xe.
Ví dụ:
- Chiều rộng: Nhiều xe moóc ở Hoa Kỳ có chiều rộng là 8 feet 6 inch, tương đương 2.590,8 mm. Nếu làm tròn thành 2.591 mm,thì xe sẽ có chiều rộng lớn hơn 8 foot 6 inch, tức là xe sẽ được phân loại là xe quá khổ trên đường ở Hoa Kỳ. Sau đó, việc này sẽ dẫn đến một tuyến đường được tính toán theo các quy tắc ràng buộc khác biệt đáng kể so với dự kiến.
- Chiều cao: Tuyến đường đi qua cầu cao 3,35 m sẽ không phù hợp với xe đầu kéo thông thường có chiều cao 4,11 m. Tuy nhiên, những chiếc xe tải thùng nhỏ hơn, khoảng 3 mét, có thể đi qua hầm chui. Do đó, bạn cần phải chỉ định chính xác các thuộc tính của xe.
Sau đây là đoạn mã cho thấy một đối tượng vehicleInfo mẫu:
"vehicleInfo": {
"totalAxleCount": 5,
"totalHeightMm": 4114,
"totalLengthMm": 21945,
"totalWidthMm": 2590,
"totalWeightKg": 32658,
"trailerInfo": [{
"lengthMm": 16154
}
vehicleInfo trường đối tượng
Bảng sau đây cho thấy tất cả định nghĩa về xe và tải trọng mà bạn có thể gửi cùng với yêu cầu.
| Trường | Nội dung mô tả | Ghi chú / Giá trị |
|---|---|---|
totalHeightMm
|
Chiều cao tối đa của xe. | Tính bằng milimet, làm tròn xuống. Hãy xem phần Chuyển đổi từ hệ đo lường Anh sang hệ mét để biết thêm thông tin chi tiết về cách làm tròn. |
totalWidthMm
|
Chiều rộng tối đa của xe. | Tính bằng milimet, làm tròn xuống. |
totalLengthMm
|
Tổng chiều dài của xe và mọi rơ moóc. | Tính bằng milimet, làm tròn xuống. |
totalWeightKg
|
Tổng trọng lượng xe (bao gồm cả rơ moóc và tải trọng). | Tính bằng kilôgam, làm tròn xuống. |
totalAxleCount
|
Tổng số trục trên xe và mọi rơ moóc. | Chính xác. |
trailerInfo (Không bắt buộc)
|
Một mảng đối tượng, mỗi đối tượng cho một đoạn giới thiệu. | Bỏ qua đối với xe không có rơ moóc, chẳng hạn như xe tải thùng. |
hazardousGoodsTypes (Không bắt buộc)
|
Một mảng chỉ định mọi vật liệu nguy hiểm trên tàu. | EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER |
Sử dụng mặt nạ trường
Để có kết quả tốt nhất, hãy thêm tiêu đề X-Goog-FieldMask vào yêu cầu của bạn để chỉ định chính xác những trường bạn muốn trong phản hồi. Mặt nạ trường giúp giảm độ trễ và đảm bảo bạn nhận được các trường tư vấn quan trọng. Tối thiểu, hãy luôn đưa routes.travelAdvisory.routeRestrictionsPartiallyIgnored vào mặt nạ trường, vì điều này cho biết tuyến đường có một hoặc nhiều quy định hạn chế áp dụng cho xe của bạn hay không.
Để biết thêm thông tin chi tiết về FieldMasks với Routes API, hãy xem bài viết này.
Đường thu phí
Để ưu tiên các tuyến đường không thu phí, hãy chỉ định avoidTolls trong thuộc tính routeModifiers của yêu cầu. Để biết thêm thông tin về đối tượng sửa đổi tuyến đường, hãy xem phần Chỉ định các đặc điểm tuyến đường cần tránh.
Việc chỉ định avoidTolls không đảm bảo rằng tuyến đường không có trạm thu phí sẽ được trả về trong phản hồi. Trong một số trường hợp, bạn phải sử dụng đường có thu phí để di chuyển giữa điểm xuất phát và điểm đến. Nếu bạn đưa routes.warnings vào mặt nạ trường của yêu cầu API Routes, thì các tuyến đường có thu phí sẽ được chú thích tương ứng trong trường này.
Các hành vi định tuyến khác
Khi bạn đặt travelMode thành TRUCK, API sẽ tự động tối ưu hoá tuyến đường cho khả năng di chuyển của xe lớn. Các tuyến đường được tạo sẽ tránh quay đầu xe và ưu tiên đường liên bang và đường cao tốc hơn các đường nhỏ. Bạn không cần đặt thêm bất kỳ tham số hoặc đối tượng sửa đổi nào để bật các hành vi này.
Tính một tuyến đường bằng computeRoutes
Sử dụng điểm cuối computeRoutes để tính toán tuyến đường dành riêng cho xe tải giữa một điểm xuất phát và một điểm đến.
Ví dụ về yêu cầu computeRoutes
Sau đây là yêu cầu curl hoàn chỉnh cho một xe bán rơ moóc thông thường. Ví dụ này bao gồm điểm cuối, tiêu đề và nội dung yêu cầu.
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
}]
}
}
}'
Ví dụ về phản hồi computeRoutes
Sau đây là ví dụ về phản hồi cho yêu cầu trước đó ở trên. Xin lưu ý rằng trong đối tượng travelAdvisory, cờ routeRestrictionsPartiallyIgnored không được đưa vào. Điều này cho biết rằng tuyến đường không bị gắn cờ và được cho là hoàn toàn tuân thủ các thuộc tính của xe.
{
"routes": [
{
"distanceMeters": 3426,
"duration": "312s",
"travelAdvisory": {},
"routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
}
]
}
Diễn giải phản hồi computeRoutes
Yêu cầu thành công đến điểm cuối computeRoutes sẽ trả về một đối tượng phản hồi JSON chứa một hoặc nhiều tuyến đường có thể có.
Trường phản hồi chính
- Hình học tuyến đường được mã hoá:
routes.polyline. Bạn có thể dùng thông tin này để kết xuất tuyến đường trên bản đồ. - Thời gian ước tính của chuyến đi:
routes.duration(tính bằng giây). Thời gian di chuyển của tuyến đường dành cho xe lớn sử dụng một mô hình mới được huấn luyện dựa trên tốc độ di chuyển ghi nhận được của xe tải thực tế trên mạng lưới đường bộ. Bạn cũng có thể dùng giá trị này để tính thời gian đến dự kiến bằng cách cộng thời gian chuyến đi ước tính với thời gian khởi hành dự kiến. - Tổng quãng đường của tuyến đường:
routes.distanceMeters(tính bằng mét). - Mã thông báo tuyến đường:
routes.routeToken. Đây là mã thông báo mờ đại diện cho tuyến đường được tính toán chính xác. Bạn truyền mã thông báo này đến SDK Điều hướng để đảm bảo tài xế nhìn thấy cùng một tuyến đường dành riêng cho xe tải. Để biết thông tin chi tiết, hãy xem hướng dẫn về Navigation SDK cho Android hoặc iOS.
Kiểm tra cờ an toàn của tuyến đường
Khi nhận được phản hồi, việc đầu tiên bạn nên làm là kiểm tra các cờ an toàn của tuyến đường. Nếu một tuyến đường được cung cấp có một hoặc nhiều quy định hạn chế khiến tuyến đường đó không phù hợp với xe, thì bạn sẽ thấy trường travelAdvisory.routeRestrictionsPartiallyIgnored được đặt thành true.
Trường này đóng vai trò là cờ để trả lời câu hỏi: "Tuyến đường này có bị gắn cờ vì vấn đề tiềm ẩn không?"
false(hoặc bị bỏ qua trong phản hồi): Tuyến đường không bị gắn cờ. Hệ thống đã tìm thấy một tuyến đường được cho là hoàn toàn tuân thủ các tham số mà bạn cung cấp trong yêu cầu.true: Tuyến đường bị gắn cờ. Hệ thống không tìm được tuyến đường hoàn toàn tuân thủ và đã trả về một tuyến đường "tốt nhất có thể" nhưng có thể không an toàn hoặc không hợp pháp. Bạn phải hết sức thận trọng khi sử dụng tuyến đường này.
Tính toán ma trận tuyến đường (computeRouteMatrix)
Sử dụng điểm cuối computeRouteMatrix để so sánh hiệu quả thời gian di chuyển và khoảng cách giữa nhiều điểm xuất phát và điểm đến. Ví dụ: bạn có thể sử dụng hàm này để tìm xe tải gần nhất với một địa điểm lấy hàng mới. Sau khi xác định được điểm xuất phát của xe mà bạn muốn sử dụng cho mục đích của mình, bạn có thể đưa ra một computeRoutes yêu cầu để nhận thông tin chi tiết về tuyến đường và mã thông báo tuyến đường cho xe được đề xuất.
Để sử dụng computeRouteMatrix, bạn chỉ định vehicleInfo trong mỗi đối tượng origin thay vì ở gốc của yêu cầu.
Ví dụ về yêu cầu 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"
}
Ví dụ về phản hồi computeRouteMatrix
Phản hồi là một mảng, trong đó mỗi đối tượng chứa thời lượng và distanceMeters cho một cặp điểm xuất phát – điểm đến.
[
{
"originIndex": 0,
"destinationIndex": 1,
"status": {},
"distanceMeters": 392372,
"duration": "14037s",
"condition": "ROUTE_EXISTS"
},
{ ... }
]
Các bước tiếp theo
- Cung cấp tính năng chỉ đường từng chặng: Tìm hiểu cách sử dụng
routeTokentrong SDK chỉ đường cho Android hoặc iOS. - Tối ưu hoá ở cấp đội xe: Sử dụng Route Optimization API với tính năng Định tuyến xe lớn.
- Tài liệu tham khảo API: Để xem danh sách đầy đủ tất cả các trường và giá trị có thể có, hãy xem Tài liệu tham khảo API Tuyến đường.