速限

Roads API 會傳回特定道路區段的速限。如果是路段以變速為限的路段，會傳回該區隔的預設速限。

但 Roads API 所傳回速限資料的準確度無法保證。所提供的速限資料並非即時資料，可能為估計、不正確、不完整和/或過時。請參閱覆蓋範圍詳細資料，瞭解可提供速度限制資料的區域。

要求

速限要求必須透過 HTTPS 傳送，格式如下：

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

參數使用方式

必要參數

  • path 或 placeId 參數。
    • path — 最多包含 100 個代表路徑的經緯度組合清單。緯度和經度值必須以半形逗號分隔。緯度/經度組合必須以直立線字元 ("|") 分隔。當您提供 path 參數時，API 會先將車輛行駛至最有可能行駛的道路 (如同 snapToRoads 要求)，然後判斷相關道路段的速度限制。如果您不希望 API 擷取路徑，您必須按照以下說明傳遞 placeId 參數。以下範例顯示含有三個緯度/經度組合的 path 參數：path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796。
    • placeId — 代表一或多個道路區隔的地點 ID。 請確認每個地點 ID 指的是路段，而非不同類型的地點。每次要求最多可傳遞 100 個地點 ID。這個 API 不會針對所提供的地點 ID 執行道路 - 點心。 回應包含要求中每個地點 ID 的速限。 您可以傳送 snapToRoads 或 nearestRoads 要求來找出相關地點 ID，然後將這些 ID 做為 speedLimits 要求的輸入內容。以下範例顯示含有兩個地點 ID 的 placeId 參數：placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
  • key：應用程式的 API 金鑰。每次要求時，應用程式都必須包含一個 API 金鑰，以便向 Roads API 傳送要求。瞭解如何取得金鑰。

選用參數

  • units — 以公里或小時為單位傳回速限。可設為 KPH 或 MPH。預設為 KPH。

回應

speedLimits 回應中可能會顯示以下元素：

  • speedLimits：道路中繼資料的陣列。每個元素都由下列欄位組成：
    • placeId：地點的專屬識別碼。Roads API 傳回的所有地點 ID 都會對應至道路區隔。
    • speedLimit — 該路段的速限。
    • units — 傳回 KPH 或 MPH。
  • snappedPoints — 對齊點的陣列。只有在要求中包含 path 參數時，這個陣列才會顯示。每個路徑都是由下列欄位組成：
    • location — 包含 latitude 和 longitude 值。
    • originalIndex：表示原始要求中對應值的整數。要求中的每個值都應對應至回應中的已取值。這些值是從 0 建立索引，因此 originalIndex 為 4 的點將是傳遞至 path 參數的第 5 個緯度/經度的貼齊值。
    • placeId：地點的專屬識別碼。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，而不是使用經緯度組合。我們建議您使用 snapToRoads 或 nearestRoads 要求取得道路區段的地點 ID。當您傳遞地點 ID 時，API 會傳回每個地點 ID 代表的道路速限。API 不會針對提供的地點 ID 提供任何道路遮蔽。

下列範例會要求在葡萄牙里斯本的 Vasco da Gama 橋上進行部分路段的速限。

要求

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 橋接說明概念；這個橋接器支援跨越裡約河的穿越 E90 公路的道路。橋接器本身俱有地點 ID 為 ChIJUzt97ZEwGQ0RM1JzQfqoDtU。上述回應中的第一個路段屬於 E90 公路的一部分，地點 ID 為 ChIJX12duJAwGQ0Ra0d4Oi4jOGE。在這個要求要求中，如果您以道路地點 ID 取代道路地點 ID，那麼在回應中，speedLimits 陣列中只會有兩項速限，因為橋接地點 ID 不參照個別道路段。此外，如果沒有任何地點 ID 用於道路區段，則回應不會包含任何速限。

使用地點 ID 提出速限要求時，請確認每個地點 ID 參照道路區隔，而不是不同地點類型。使用 snapToRoads 或 nearestRoads 要求來擷取個別道路片段的地點 ID，兩者均可從單一呼叫傳回多個地點 ID。