Phương thức computeRoutes (REST) và phương thức ComputeRoutes (gRPC) đều trả về tuyến được biểu thị bằng hình nhiều đường trong phản hồi. Các API này trả về 2 loại hình nhiều đường:
Hình nhiều đường cơ bản (mặc định), thể hiện một tuyến đường nhưng không có thông tin giao thông được nhúng trong hình nhiều đường. Các yêu cầu trả về một hình nhiều đường cơ bản sẽ được tính phí theo cước phí Tuyến đường cơ bản. Tìm hiểu thêm về việc thanh toán cho Routes API.
Hình nhiều đường nhận biết 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ị dưới dạng danh mục tốc độ (
NORMAL
,SLOW
,TRAFFIC_JAM
) áp dụng trên một khoảng thời gian nhất định của hình nhiều đường. Các yêu cầu hình nhiều đường nhận biết lưu lượng truy cập sẽ được tính phí theo mức phí Ưu tiên của Tuyến đường. Tìm hiểu thêm về cách thanh toán cho API Tuyến đường. Để biết thông tin chi tiết, hãy xem phần Định cấu hình chất lượng hình nhiều đường
Để biết thêm thông tin về hình nhiều đường, hãy xem:
Tiện ích bộ mã hoá nhiều đường tương tác cho phép bạn tạo các hình nhiều đường đã mã hoá trong giao diện người dùng hoặc giải mã các hình nhiều đường để hiển thị trên bản đồ. Ví dụ: sử dụng tiện ích này để giải mã hình nhiều đường được tạo bằng mã dưới đây.
Yêu cầu hình nhiều đường cơ bản cho một tuyến đường, chân hoặc bước
Hình nhiều đường được biểu thị bằng một đối tượng Polyline (REST) hoặc Polyline (gRPC). Bạn có thể trả về một hình nhiều đường trong phản hồi ở cấp độ tuyến đường, chân 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 định tuyến, hãy trả về một hình nhiều đường trong phản hồi bằng cách đưa
routes.polyline
vào mặt nạ trường (field mask) của phản hồi.Ở cấp độ chân, hãy trả về một hình nhiều đường trong phản hồi cho mỗi chặng của tuyến đường bằng cách thêm
routes.legs.polyline
.Ở 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ân bằng cách thêm
routes.legs.steps.polyline
.
Ví dụ: để trả về một hình nhiều đườ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 hình nhiều đườ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 nguồn gốc và một đích đến, nên tuyến được trả về chỉ chứa một chân duy nhất. Do đó, hình nhiều đường cho chân 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 được trả về sẽ chứa hai chân:
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ề hai chân, mỗi chân có một hình nhiều đường duy nhất và một hình nhiều đườ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
Chất lượng của hình nhiều đường có thể được mô tả trong các thuật ngữ sau:
Độ chính xác của dấu phẩy động của các điểm
Các điểm được chỉ định là giá trị vĩ độ và kinh độ, biểu thị ở định dạng dấu phẩy động có độ chính xác đơn. Cách 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 giảm khi các giá trị tăng do lỗi làm tròn dấu phẩy động.
Trong phương thức computeRoutes (REST) và ComputeRoutes, tuỳ chọn này do
polylineEncoding
kiểm soát.Số điểm tạo nên hình nhiều đường
Càng có nhiều điểm thì hình nhiều đường càng mượt mà (đặc biệt là trong các đường cong).
Trong phương thức computeRoutes (REST) và ComputeRoutes, tuỳ chọn này do
polylineQuality
kiểm soát.
Định cấu hình loại mã hoá nhiều đường
Sử dụng tuỳ chọn yêu cầu polylineEncoding
để kiểm soát loại hình nhiều đường.
Thuộc tính polylineEncoding
kiểm soát việc hình nhiều đường có được mã hoá thành ENCODED_POLYLINE
(mặc định) hay không, tức là sẽ sử dụng Định dạng thuật toán nhiều dòng đã mã hoá hay GEO_JSON_LINESTRING
, có nghĩa là sẽ sử dụng định dạng GeoJSON LineString.
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 Poyline
polylineQuality
chỉ định chất lượng của hình nhiều đường là HIGH_QUALITY
hoặc OVERVIEW
(mặc định). Với OVERVIEW
, hình nhiều đường được tạo thành bằng một số ít điểm và có độ trễ yêu cầu thấp hơn 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 hình nhiều đường nhận biết lưu lượng truy cập
Các ví dụ nêu trên đều trả về hình nhiều đường cơ bản, nghĩa là hình nhiều đường không có thông tin về lưu lượng truy cập. Ngoài ra, bạn cũng có thể yêu cầu hình nhiều đường chứa thông tin về giao thông cho tuyến đường và cho từng chặng của tuyến đường.
Hình nhiều đường có nhận biết 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ị dưới dạng danh mục tốc độ (NORMAL
, SLOW
, TRAFFIC_JAM
) trong một khoảng thời gian nhất định của hình nhiều đường phản hồi. Các khoảng thời gian được xác định bởi chỉ mục điểm nhiều đường bắt đầu (bao gồm) và kết thúc (loại trừ).
Ví dụ: phản hồi sau đây cho thấy lưu lượng truy cập NORMAL
giữa điểm nhiều đường 2 và 4:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Để gửi yêu cầu tính toán hình nhiều đường nhận biết lưu lượng truy cập, hãy đặt các thuộc tính sau trong yêu cầu:
Đặt trường mảng
extraComputations
thànhTRAFFIC_ON_POLYLINE
để bật tính năng tính lưu lượng truy cập.Đặt
travelMode
thànhDRIVE
hoặcTWO_WHEELER
. Yêu cầu đối với mọi chế độ đi lại khác sẽ trả về một lỗi.Chỉ định lựa chọn ưu tiên định tuyến
TRAFFIC_AWARE
hoặcTRAFFIC_AWARE_OPTIMAL
trong 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 và độ trễ.Đặt mặt nạ cho trường (field mask) để chỉ định trả về các thuộc tính phản hồi:
Ở cấp tuyến đường, hãy trả về mọi thông tin di chuyển trong phản hồi bằng cách đưa
routes.travelAdvisory
vào mặt nạ trường (field mask) của phản hồi. Để chỉ trả về thông tin lưu lượng truy cập, hãy chỉ địnhroutes.travelAdvisory.speedReadingIntervals
Ở cấp độ chân, 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 thêm
routes.legs.travelAdvisory
. Để chỉ trả về thông tin lưu lượng truy cập, 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 hình nhiều đường nhận biết lưu lượng truy cập
Trong phản hồi này, dữ liệu giao thông được mã hoá bằng hình nhiều đường và nằm trong trường travelAdvisory
, thuộc loại đối tượng RouteLegTravelAdvisory (từng chặng) và đối tượng RouteTravelAdvisory (tuyến).
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 độ lưu lượng truy cập. Mỗi đối tượng trong mảng được biểu thị bằng một đối tượng SpeedReadingInterval (REST) hoặc SpeedReadingInterval (gRPC).
Đối tượng SpeedReadingInterval
bao gồm việc đọc tốc độ trong một khoảng thời gian định tuyến, chẳng hạn như NORMAL
, SLOW
hoặc TRAFFIC_JAM
. Toàn bộ mảng đối tượng bao phủ toàn bộ hình nhiều đường của tuyến đường mà không chồng chéo nhau. Điểm bắt đầu của một khoảng thời gian được chỉ định giống với điểm kết thúc 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.
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 từ chỉ mục 2 đến chỉ mục 4 là như nhau.
Hiển thị hình nhiều đường nhận biết giao thông bằng SDK Maps
Bạn nên hiển thị các hình nhiều đường nhận biết 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à hoa văn tuỳ chỉnh dọc theo các đoạn kéo dài hình nhiều đường. Để biết thêm thông tin chi tiết về cách sử dụng hình nhiều đường, hãy xem Tính năng hình nhiều đường dành cho Android và Tính năng hình nhiều đường dành cho iOS.
Ví dụ về kết xuất hình nhiều đường
Người dùng SDK Maps có cơ hội xác định logic ánh xạ tuỳ chỉnh giữa các danh mục tốc độ và giản đồ kết xuất hình nhiều đường. Ví dụ: người dùng có thể quyết định hiển thị tốc độ "BÌNH THƯỜNG" 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 đường màu cam đậm chẳng hạn.
Các đoạn mã sau đây thêm một đường nhiều đường màu xanh dương đậm với 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 hình nhiều đườ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