速限

Roads API 會傳回特定道路路段的張貼速度限制。如果路段有變動速度限制,則會傳回該區隔的預設速限。

我們無法保證 Roads API 傳回的速限資料準確度。提供的速度限制資料並非即時資料,因此可能為預估、不正確、不完整和/或過時。請參閱涵蓋範圍詳細資料,瞭解支援速度限制資料的區域。

要求

速度限制要求必須透過 HTTPS 傳送,採用下列形式:

https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY

參數使用狀況

必要參數

  • pathplaceId 參數。
    • path:最多 100 個代表路徑的經緯度組合清單。緯度值和經度值必須以半形逗號分隔。緯度/經度組合必須以直立線字元 (「|」) 分隔。提供 path 參數時,API 會先先將路徑傳遞至車輛最有可能行駛的道路 (就像 snapToRoads 要求一樣),然後判斷相關路段的速限。如果您不希望 API 貼齊路徑,則必須傳遞 placeId 參數 (如下所述)。以下範例顯示包含三個經緯度組合的 path 參數:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
    • placeId:地點,代表一或多個路段。確認每個地點 ID 都是指特定路段,而不是不同類型的地點。每項要求最多可以傳送 100 個地點 ID。API 不會針對提供的地點 ID 執行道路插入作業。回應中包含要求中每個地點 ID 的速限。您可以傳送 snapToRoadsnearestRoads 要求,找出相關的地點 ID,並將其做為 speedLimits 要求的輸入內容。以下範例顯示包含兩個地點 ID 的 placeId 參數:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
  • key:應用程式的 API 金鑰。每次傳送要求給 Roads API 時,應用程式都必須識別,然後在要求中納入 API 金鑰。瞭解如何取得金鑰

選用參數

  • units - 是否傳回公里數或公里的速限。可設為 KPHMPH。預設為 KPH

回應

speedLimits 回應中可能有下列元素:

  • speedLimits:道路中繼資料陣列。每個元素都包含下列欄位:
    • placeId:地點的專屬 ID。Roads API 傳回的所有地點 ID 會對應到路段。
    • speedLimit:該路段的速限。
    • units — 傳回 KPHMPH
  • snappedPoints:對齊點的陣列。只有要求包含 path 參數時,系統才會顯示這個陣列。每個點都包含下列欄位:
    • location — 包含 latitudelongitude 值。
    • originalIndex:一個整數,表示原始要求中的對應值。要求中的每個值都應對應至回應中的已對應值。這些值是從 0 建立索引,因此 originalIndex 點的 4 點會傳遞至 path 參數的第 5 個緯度/經度對齊值。
    • placeId:地點的專屬 ID。Roads API 傳回的所有地點 ID 都會對應至道路路段。您可以在速限要求中傳遞 placeId,藉此決定該路段的速限。
  • warning_message — 包含向使用者顯示警告的字串。

使用路徑的要求範例

這個要求會取得在葡萄牙里斯本 (Vasco da Gama Bridge) 穿越路線中,與指定經緯度配對最近的速限。

要求

https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY

回應

{
  speedLimits:
  [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ],
  snappedPoints:
  [
    {
      location:
      {
        latitude: 38.75807927603043,
        longitude: -9.037417546438084
      },
      originalIndex: 0,
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE"
    },
    {
      location:
      {
        latitude: 38.689653701836896,
        longitude: -9.177051486847693
      },
      originalIndex: 1,
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU"
    },
    {
      location:
      {
        latitude: 41.13993011767777,
        longitude: -8.609400794783655
      },
      originalIndex: 2,
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M"
    }
  ],
  warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation."
}

請注意,在上述回應中收到有關法律用途的警告訊息。如果您要要求任意點的最近路段有速限,則必須使用從 nearestRoads 端點擷取的地點 ID 呼叫 speedLimits

使用地點 ID 的要求範例

除了使用經緯度組合之外,您也可以傳遞路段的地點 ID。建議您使用 snapToRoadsnearestRoads 要求取得道路地點 ID。傳送地點 ID 時,API 會傳回每個地點 ID 代表的路段速限。API 不會對任何提供的地點 ID 套用任何道路插入設定。

以下範例會要求跨葡萄牙里斯本 (Vasco da Gama Bridge) 橫跨部分路段的速限。

要求

https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY

回應

{
  "speedLimits": [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ]
}

使用建議

為盡量減少對速限服務的呼叫量,建議您以 5 到 15 分鐘的間隔取樣資產位置 (實際值取決於資產的傳輸速度)。針對未移動的資產,只要一個位置樣本就夠了 (不需要多次呼叫)。

建議您在累積到一定的資料量後,才呼叫速限服務,而不是每收到一次行動資產的位置就呼叫 API;這樣有助於減少整體延遲時間。

為什麼少了部分或所有速限?

缺少 speedLimits 最常見的原因,是要求非路段的速限。

以上範例使用 Vasco da Gama 橋樑來說明概念;橋樑橫跨 Eio Tejo 道路。橋接器本身的地點 ID 為 ChIJUzt97ZEwGQ0RM1JzQfqoDtU。上述回應的第一個路段是 E90 道路的一部分,地點 ID 為 ChIJX12duJAwGQ0Ra0d4Oi4jOGE。在要求範例中,如果您將道路地點 ID 替換成橋接地點的地點 ID,則回應中 speedLimits 陣列只會有兩條速限,因為橋接器的地點 ID 不會參照個別道路路段。此外,如果路段沒有地點 ID,則回應不會包含任何速度限制。

使用地點 ID 提出速限要求時,請確認每個地點 ID 都是指特定路段,而非其他類型的地點。針對個別路段的地點 ID,建議您使用 snapToRoadsnearestRoads 要求來擷取,且兩者皆可透過單一呼叫傳回多個地點 ID。