Routes API 可讓您根據路況感知折線來查詢路況狀況的相關資訊。流量條件的反應速度是以回應回應折線的指定間隔速度類別 (NORMAL
、SLOW
、TRAFFIC_JAM
) 表示。間隔由起始 (包含) 與結束 (不含) 折線點的索引所定義。
如要進一步瞭解折線,請參閱:
- 設定品質與延遲時間的比較,瞭解設定子質品質的相關資訊
- 編碼折線演算法格式說明瞭對折線進行編碼的演算法,
- 互動式折線編碼公用程式可讓您在使用者介面中建立編碼折線,或解碼折線以在地圖上顯示折線。例如,使用此公用程式,解碼由下方程式碼建立的折線。
傳回折線
折線會以 Polyline (REST) 或 Polyline (gRPC) 物件表示。在路徑和路段層級中,您都可以傳回折線。
使用回應欄位遮罩來控制要傳回的折線:
在路徑層級:在回應欄位遮罩中加入
routes.polyline
,以在回應中傳回折線。在路段層級:加入
routes.legs.polyline
,在路徑的每段路線中傳回折線。
例如,如要傳回整個路線和每段路段的折線:
X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline
設定折線類型
computeRoutes 方法 (REST) 和 ComputeRoutes 方法 (gRPC) 支援控制折線類型的 polylineEncoding
要求選項。
polylineEncoding
指定如何將折線編碼為 ENCODED_POLYLINE
(預設值),表示使用折線編碼演算法,或是 GEO_JSON_LINESTRING
(表示使用 GeoJSON LineString 格式)。
例如,在要求主體中:
{ "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": "2019-10-15T15:01:23.045123456Z", ... }
回傳路況資訊
您可以設定回應來納入收費路段及可能的交通區域限制:
在路徑層級,這項資訊包含在 RouteTravelAdvisory (REST) 或 RouteTravelAdvisory (gRPC) 物件中。
在腿部層級,此資訊包含在 RouteLegTravelAdvisory (REST) 或 RouteLegTravelAdvisory (gRPC) 物件中。
RouteTravelAdvisory 和 RouteLegTravelAdvisory 都包含一個陣列欄位,用於提供流量密度詳細資訊,其中包含流量密度。陣列中的每個物件都以 SpeedReadingInterval (REST) 或 SpeedReadingInterval (gRPC) 物件表示。
SpeedReadingInterval 物件包含路線間隔的速度讀取。整個物件陣列會覆蓋路徑的完整折線,且不會重疊。指定間隔的起始點與前一段間隔的結束時間相同。
如要設定使用折線傳迴路況資訊的方法,請使用回應欄位遮罩:
在路徑層級中,在回應欄位遮罩中加入
routes.travelAdvisory
,即可傳回回應中的所有流量資訊。如果只要傳回 SpeedReadingInterval,請指定routes.travelAdvisory.speedReadingIntervals
在路段層級時,請在
routes.legs.travelAdvisory.speedReadingIntervals
或routes.legs.steps.travelAdvisory.speedReadingIntervals
中加入回應中每個路線的車流量資訊,
傳迴路況資訊時,您通常會在回應中傳回折線和路況資訊:
X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.travelAdvisory,routes.legs.polyline,routes.legs.travelAdvisory
流量感知折線的回應範例
回應中的 routes.travelAdvisory.speedReadingIntervals
會提供路徑層級流量。系統會在 routes.legs.travelAdvisory.speedReadingIntervals
下提供車流層級流量。
每個間隔都透過其 startPolylinePointIndex
、endPolylinePointIndex
和對應的速度類別來描述。請注意,根據 proto3 做法,在間隔內沒有起始索引與索引 0 對應。
startPolylinePointIndex
和 endPolylinePointIndex
值不一定連續。例如:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
在這種情況下,從第 2 個索引到第 4 個索引的路況都一樣。
完整回應如下所示:
{ "routes": [ { "legs": { "polyline": { "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD" }, "travelAdvisory": { "speedReadingIntervals": [ { "endPolylinePointIndex": 1, "speed": "NORMAL" }, { "startPolylinePointIndex": 1, "endPolylinePointIndex": 2, "speed": "SLOW" }, { "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" } ] } }, "polyline": { "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD" }, "travelAdvisory": { "speedReadingIntervals": [ { "endPolylinePointIndex": 1, "speed": "NORMAL" }, { "startPolylinePointIndex": 1, "endPolylinePointIndex": 2, "speed": "SLOW" }, { "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" } ] } } ] }
使用 Maps SDK 顯示路況感知折線
我們建議您使用 Google Maps SDK 提供的各種地圖項目,在地圖上顯示車流量線折線,包括自訂色彩、筆劃和折線延伸圖案等。想進一步瞭解如何使用折線,請參閱Android 的折線功能和 iOS 的折線功能。
折線轉譯範例
Maps SDK 的使用者有機會定義速度類別與折線轉譯結構定義之間的自訂對應邏輯。例如,一個人可能會決定在地圖上以粗藍色線條顯示「NORMAL」的速度,而「SLOW」的速度則顯示為有粗的橘色線條,依此類推。
下列程式碼片段會針對墨爾本至伯斯的測地線段,加上粗的藍色折線。詳情請參閱自訂外觀 (適用於 Android) 與自訂折線 (適用於 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