Phương thức computeRoutes (REST) và phương thức ComputeRoutes (gRPC) đều trả về tuyến đường được biểu thị bằng một đường nhiều đoạn thẳng như một phần của phản hồi. Các API này trả về 2 loại đường nhiều đoạn thẳng:
Đường nhiều đoạn thẳng cơ bản (mặc định), biểu thị một tuyến đường nhưng không có thông tin giao thông được nhúng trong đường nhiều đoạn thẳng. Các yêu cầu trả về một đường nhiều đoạn thẳng cơ bản sẽ được tính phí theo mức giá Cơ bản của Routes. Tìm hiểu thêm về cách tính phí cho Routes API.
Đường nhiều đoạn thẳng có thông tin giao thông, chứa thông tin về tình trạng giao thông dọc theo tuyến đường. Tình trạng giao thông được biểu thị bằng các danh mục tốc độ (
NORMAL,SLOW,TRAFFIC_JAM) áp dụng cho một khoảng thời gian nhất định của đường nhiều đoạn thẳng. Các yêu cầu về đường nhiều đoạn thẳng có thông tin giao thông sẽ được tính phí theo mức giá Ưu tiên của Routes. Tìm hiểu thêm về cách tính phí cho Routes API. Để biết thông tin chi tiết, hãy xem bài viết Định cấu hình chất lượng đường nhiều đoạn thẳng
Để biết thêm thông tin về đường nhiều đoạn thẳng, hãy xem:
Tiện ích Bộ mã hoá đường nhiều đoạn thẳng tương tác cho phép bạn tạo đường nhiều đoạn thẳng được mã hoá trong giao diện người dùng hoặc giải mã đường nhiều đoạn thẳng để hiển thị trên bản đồ. Ví dụ: hãy sử dụng tiện ích này để giải mã một đường nhiều đoạn thẳng do mã bên dưới tạo.
Yêu cầu một đường nhiều đoạn thẳng cơ bản cho một tuyến đường, chặng hoặc bước
Đường nhiều đoạn thẳng được biểu thị bằng một Polyline (REST) hoặc Polyline (gRPC) đối tượng. Bạn có thể trả về một đường nhiều đoạn thẳng trong phản hồi ở cấp tuyến đường, chặng và bước.
Chỉ định hình nhiều đường cần trả về bằng cách sử dụng mặt nạ trường phản hồi:
Ở cấp tuyến đường, hãy trả về một hình nhiều đường trong phản hồi bằng cách đưa
routes.polylinevào mặt nạ trường phản hồi.Ở cấp chặng, hãy trả về một hình nhiều đường trong phản hồi cho từng chặng của tuyến đường bằng cách đưa
routes.legs.polylinevào.Ở cấp bước, hãy trả về một hình nhiều đường trong phản hồi cho từng bước của chặng bằng cách đưa
routes.legs.steps.polylinevào.
Ví dụ: để trả về một đường nhiều đoạn thẳng cho toàn bộ tuyến đường, cho từng chặng và cho từng bước của mỗi chặng:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Yêu cầu này trả về phản hồi sau đây, bao gồm đường nhiều đoạn thẳng cho tuyến đường, cho từng chặng của tuyến đường và cho từng bước của chặng:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } }, "steps": [ { "polyline": { "encodedPolyline": "kclcF...@sC@YIOKI" } }, { "polyline": { "encodedPolyline": "wblcF~...SZSF_@?" } }, ... ], "distanceMeters": 56901, "duration": "2420s", "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } } ] }
Vì yêu cầu này chỉ chứa một điểm khởi hành và một điểm đến, nên tuyến đường được trả về chỉ chứa một chặng. Do đó, hình nhiều đường cho chặng và cho tuyến đường là giống nhau.
Nếu bạn thêm một điểm tham chiếu trung gian vào yêu cầu, thì tuyến đường được trả về sẽ chứa 2 chặng:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "intermediates": [ { "address": "450 Serra Mall, Stanford, CA 94305, USA"}, ], "travelMode": "DRIVE", }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Yêu cầu này trả về 2 chặng, mỗi chặng có một đường nhiều đoạn thẳng riêng biệt và một đường nhiều đoạn thẳng cho toàn bộ tuyến đường:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG" } "steps": [ { "polyline": { "encodedPolyline": "kclcFfqch...YIOKI" } }, ... }, { "polyline": { "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G" } "steps": [ { "polyline": { "encodedPolyline": "uypeFbo`jVgJq...PoBiC" } }, ... } ], "distanceMeters": 68403, "duration": "3759s", "polyline": { "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE" } } ] }
Chất lượng hình nhiều đường
Bạn có thể mô tả chất lượng của một hình nhiều đường theo các điều khoản sau:
Độ chính xác dấu phẩy động của các điểm
Các điểm được chỉ định dưới dạng giá trị vĩ độ và kinh độ, được biểu thị ở định dạng dấu phẩy động có độ chính xác đơn. Điều này phù hợp với các giá trị nhỏ (có thể được biểu thị chính xác), nhưng độ chính xác sẽ giảm khi giá trị tăng do lỗi làm tròn dấu phẩy động.
Trong computeRoutes (REST) và ComputeRoutes, điều này được kiểm soát bởi
polylineEncoding.Số điểm tạo nên hình nhiều đường
Càng có nhiều điểm, đường nhiều đoạn thẳng càng mượt mà (đặc biệt là ở các đường cong).
Trong computeRoutes (REST) và ComputeRoutes, điều này được kiểm soát bởi
polylineQuality.
Định cấu hình loại mã hoá đường nhiều đoạn thẳng
Sử dụng tuỳ chọn yêu cầu polylineEncoding để kiểm soát loại đường nhiều đoạn thẳng. Thuộc tính
polylineEncoding kiểm soát việc đường nhiều đoạn thẳng sẽ được mã hoá dưới dạng
ENCODED_POLYLINE (mặc định), nghĩa là Định dạng
Thuật toán đường nhiều đoạn thẳng được mã hoá sẽ được sử dụng, hoặc
GEO_JSON_LINESTRING, nghĩa là định dạng GeoJSON LineString sẽ được sử dụng.
Ví dụ: trong nội dung yêu cầu:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "polylineEncoding": "ENCODED_POLYLINE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Định cấu hình chất lượng đường nhiều đoạn thẳng
polylineQuality chỉ định chất lượng của đường nhiều đoạn thẳng là HIGH_QUALITY hoặc OVERVIEW (mặc định). Với OVERVIEW, hình nhiều đường được tạo bằng một số lượng nhỏ điểm và có độ trễ yêu cầu thấp hơn so với HIGH_QUALITY.
Ví dụ: trong nội dung yêu cầu:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE", "polylineQuality": "HIGH_QUALITY", "polylineEncoding": "ENCODED_POLYLINE", "departureTime": "2023-10-15T15:01:23.045123456Z", ... }
Yêu cầu một đường nhiều đoạn thẳng có thông tin giao thông
Các ví dụ được trình bày ở trên đều trả về đường nhiều đoạn thẳng cơ bản, nghĩa là đường nhiều đoạn thẳng không có thông tin giao thông. Ngoài ra, bạn cũng có thể yêu cầu hình nhiều đường chứa thông tin giao thông cho tuyến đường và cho từng chặng của tuyến đường.
Đường nhiều đoạn thẳng có thông tin giao thông chứa thông tin về tình trạng giao thông dọc theo tuyến đường. Tình trạng giao thông được biểu thị bằng các danh mục tốc độ (NORMAL, SLOW, TRAFFIC_JAM) cho một khoảng thời gian nhất định của đường nhiều đoạn thẳng phản hồi.
Các khoảng thời gian được xác định bằng chỉ mục của các điểm bắt đầu (bao gồm) và kết thúc (không bao gồm) của đường nhiều đoạn thẳng.
Ví dụ: phản hồi sau đây cho thấy tình trạng giao thông NORMAL giữa các điểm 2 và 4 của đường nhiều đoạn thẳng:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Để đưa ra yêu cầu tính toán một đường nhiều đoạn thẳng có thông tin giao thông, hãy đặt các thuộc tính sau trong yêu cầu:
Đặt trường mảng
extraComputationsthànhTRAFFIC_ON_POLYLINEđể bật tính năng tính toán tình trạng giao thông.Đặt
travelModethànhDRIVEhoặcTWO_WHEELER. Các yêu cầu về bất kỳ phương thức di chuyển nào khác đều trả về lỗi.Chỉ định lựa chọn ưu tiên về định tuyến
TRAFFIC_AWAREhoặcTRAFFIC_AWARE_OPTIMALtrong yêu cầu. Để biết thêm thông tin, hãy xem bài viết Định cấu hình chất lượng so với độ trễ.Đặt mặt nạ trường phản hồi chỉ định trả về các thuộc tính phản hồi:
Ở cấp tuyến đường, hãy trả về tất cả thông tin di chuyển trong phản hồi bằng cách đưa
routes.travelAdvisoryvào mặt nạ trường phản hồi. Để chỉ trả về thông tin giao thông, hãy chỉ địnhroutes.travelAdvisory.speedReadingIntervalsỞ cấp chặng, hãy trả về tất cả thông tin di chuyển trong phản hồi cho từng chặng của tuyến đường bằng cách đưa
routes.legs.travelAdvisoryvào. Để chỉ trả về thông tin giao thông, hãy chỉ địnhroutes.legs.travelAdvisory.speedReadingIntervals.
curl -X POST -d '{
"origin":{
"address": "1600 Amphitheatre Parkway, Mountain View, CA"
},
"destination":{
"address": "24 Willie Mays Plaza, San Francisco, CA 94107"
},
"travelMode": "DRIVE",
"extraComputations": ["TRAFFIC_ON_POLYLINE"],
"routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'Ví dụ về phản hồi cho một đường nhiều đoạn thẳng có thông tin giao thông
Trong phản hồi, dữ liệu giao thông được mã hoá trong hình nhiều đường và có trong trường
travelAdvisory thuộc loại
RouteLegTravelAdvisory
đối tượng (mỗi chặng) và
RouteTravelAdvisory đối tượng (tuyến đường).
Ví dụ:
{
"routes": [
{
"legs": {
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the leg.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
},
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the route.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
}
]
}
Cả RouteTravelAdvisory và RouteLegTravelAdvisory đều bao gồm một trường mảng có tên là speedReadingIntervals chứa thông tin về tốc độ giao thông. Mỗi
đối tượng trong mảng được biểu thị bằng một
SpeedReadingInterval (REST) hoặc
SpeedReadingInterval
(gRPC).
Đối tượng SpeedReadingInterval bao gồm thông tin đọc tốc độ cho một khoảng thời gian của tuyến đường, chẳng hạn như NORMAL, SLOW hoặc TRAFFIC_JAM. Toàn bộ mảng đối tượng bao phủ toàn bộ đường nhiều đoạn thẳng của tuyến đường mà không bị trùng lặp. Điểm bắt đầu của một khoảng thời gian được chỉ định giống với điểm cuối của khoảng thời gian trước đó.
Mỗi khoảng thời gian được mô tả bằng startPolylinePointIndex, endPolylinePointIndex và danh mục tốc độ tương ứng. Xin lưu ý rằng việc thiếu chỉ mục bắt đầu trong khoảng thời gian tương ứng với chỉ mục 0 theo các phương pháp proto3.
Giá trị startPolylinePointIndex và endPolylinePointIndex không phải lúc nào cũng liên tiếp. Ví dụ:
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
Trong trường hợp này, tình trạng giao thông giống nhau từ chỉ mục 2 đến chỉ mục 4.
Hiển thị đường nhiều đoạn thẳng có thông tin giao thông bằng Maps SDK
Bạn nên hiển thị đường nhiều đoạn thẳng có thông tin giao thông trên bản đồ bằng cách sử dụng nhiều tính năng do SDK Google Maps cung cấp, bao gồm cả màu sắc, nét vẽ và mẫu tuỳ chỉnh dọc theo các đoạn đường nhiều đoạn thẳng. Để biết thêm thông tin chi tiết về cách sử dụng đường nhiều đoạn thẳng, hãy xem Các tính năng của đường nhiều đoạn thẳng cho Android và Các tính năng của đường nhiều đoạn thẳng cho iOS.
Ví dụ về cách hiển thị đường nhiều đoạn thẳng
Người dùng Maps SDK có thể xác định logic ánh xạ tuỳ chỉnh giữa các danh mục tốc độ và lược đồ kết xuất hình ảnh đường nhiều đoạn thẳng. Ví dụ: một người có thể quyết định hiển thị tốc độ "NORMAL" dưới dạng một đường màu xanh dương đậm trên bản đồ, trong khi tốc độ "SLOW" có thể được hiển thị dưới dạng một đường màu cam đậm.
Các đoạn mã sau đây thêm một đường nhiều đoạn thẳng màu xanh dương đậm có các đoạn trắc địa từ Melbourne đến Perth. Để biết thêm thông tin, hãy xem bài viết Tuỳ chỉnh giao diện (dành cho Android) và Tuỳ chỉnh đường nhiều đoạn thẳng (dành cho iOS).
Android
Java
Polyline line = map.addPolyline(new PolylineOptions() .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734)) .width(25) .color(Color.BLUE) .geodesic(true));
Kotlin
val line: Polyline = map.addPolyline( PolylineOptions() .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734)) .width(25f) .color(Color.BLUE) .geodesic(true) )
iOS
Objective-C
GMSMutablePath *path = [GMSMutablePath path]; [path addLatitude:-37.81319 longitude:144.96298]; [path addLatitude:-31.95285 longitude:115.85734]; GMSPolyline *polyline = [GMSPolyline polylineWithPath:path]; polyline.strokeWidth = 10.f; polyline.strokeColor = .blue; polyline.geodesic = YES; polyline.map = mapView;
Swift
let path = GMSMutablePath() path.addLatitude(-37.81319, longitude: 144.96298) path.addLatitude(-31.95285, longitude: 115.85734) let polyline = GMSPolyline(path: path) polyline.strokeWidth = 10.0 polyline.geodesic = true polyline.map = mapView
Sử dụng đường nhiều đoạn thẳng được mã hoá với tính năng Tìm kiếm dọc theo tuyến đường
Sử dụng tính năng Tìm kiếm văn bản của Places API để tìm kiếm dọc theo một tuyến đường đã tính toán. Bạn truyền đường nhiều đoạn thẳng được mã hoá của một tuyến đường đã tính toán trước từ Routes API Compute Routes đến yêu cầu Tìm kiếm văn bản. Sau đó, phản hồi sẽ chứa những địa điểm phù hợp với tiêu chí tìm kiếm và cũng nằm gần tuyến đường đã chỉ định. Để biết thông tin chi tiết, hãy xem bài viết tìm kiếm dọc theo một tuyến đường.
Ví dụ: để trả về các quán cà phê dọc theo tuyến đường giữa điểm khởi hành và điểm đến:
Node.js
const API_KEY = 'YOUR_API_KEY'; const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes'; const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); } async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; } init();