Routes API 目前為預先發布版 (正式發布前)。正式發布前的產品和功能支援有限,對正式發布前的產品和功能所做的變更可能與其他正式發布前的版本不相容。「正式發布前產品」受《Google 地圖平台服務專屬條款》規範。詳情請參閱發布階段說明

要求折線的流量資訊

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Routes API 可讓您根據路況感知折線來查詢路況狀況的相關資訊。流量條件的反應速度是以回應回應折線的指定間隔速度類別 (NORMALSLOWTRAFFIC_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 和 RouteLegTravelAdvisory 都包含一個陣列欄位,用於提供流量密度詳細資訊,其中包含流量密度。陣列中的每個物件都以 SpeedReadingInterval (REST) 或 SpeedReadingInterval (gRPC) 物件表示。

SpeedReadingInterval 物件包含路線間隔的速度讀取。整個物件陣列會覆蓋路徑的完整折線,且不會重疊。指定間隔的起始點與前一段間隔的結束時間相同。

如要設定使用折線傳迴路況資訊的方法,請使用回應欄位遮罩

  • 在路徑層級中,在回應欄位遮罩中加入 routes.travelAdvisory,即可傳回回應中的所有流量資訊。如果只要傳回 SpeedReadingInterval,請指定 routes.travelAdvisory.speedReadingIntervals

  • 在路段層級時,請在 routes.legs.travelAdvisory.speedReadingIntervalsroutes.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 下提供車流層級流量。

每個間隔都透過其 startPolylinePointIndexendPolylinePointIndex 和對應的速度類別來描述。請注意,根據 proto3 做法,在間隔內沒有起始索引與索引 0 對應。

startPolylinePointIndexendPolylinePointIndex 值不一定連續。例如:

{
  "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