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,然後在speedLimits
要求中提供這些 ID。以下範例顯示包含兩個地點 ID 的placeId
參數:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
:您應用程式的 API 金鑰。每次傳送要求給 Roads API 時,您的應用程式都必須識別本身,也就是每次要求時都要附上 API 金鑰。瞭解如何取得金鑰。
選用參數
units
— 要傳回速限 (以公里或英里為單位)。可設為KPH
或MPH
。預設為KPH
。
回應
speedLimits
回應中可能會顯示下列元素:
speedLimits
:道路中繼資料陣列。每個元素都包含下列欄位:placeId
:地點的專屬 ID。Roads API 傳回的所有地點 ID 都會對應至路段。speedLimit
:該路段的速限。units
- 傳回KPH
或MPH
。
snappedPoints
:貼齊點的陣列。只有在要求包含path
參數時,才會顯示這個陣列。每個資料點均由下列欄位組成:location
:包含latitude
和longitude
值。originalIndex
:代表原始要求中對應值的整數。要求中的每個值都應對應至回應中的固定值。這些值已從0
建立索引,因此originalIndex
為4
的點會是傳遞至path
參數的第 5 個經緯度的貼齊值。placeId
:地點的專屬 ID。Roads API 傳回的所有地點 ID 都會對應至路段。系統會透過速限要求傳遞placeId
,藉此判斷該路段的速限。
warning_message
:包含使用者可見警告的字串。
使用路徑的要求範例
這項要求會取得每個最接近指定經緯度組合 (位於葡萄牙里斯本瓦斯科達加馬橋) 路徑的速限。
要求
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 套用任何道路釘選。
以下範例要求某些橫跨葡萄牙里斯本瓦斯科達加馬橋的路段,要求速限。
要求
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 橋接器說明概念;此橋樑支援橫跨裡約提霍 (Rio Tejo) 上的 E90 公路。橋樑本身為 ChIJUzt97ZEwGQ0RM1JzQfqoDtU。上述回應中的第一個路段屬於 E90 道路的一部分,地點 ID 為 ChIJX12duJAwGQ0Ra0d4Oi4jOGE。在範例要求中,如果您將道路地點 ID 替換成橋樑的地點 ID,則回應中 speedLimits
陣列只會有兩項速限,因為橋樑的地點 ID 不參照個別路段。此外,如果沒有任何地點 ID 適用於路段,回應就不會包含任何速限。
使用地點 ID 提出速限要求時,請確認每個地點 ID 都參照了路段,而不是其他類型的地點。如要擷取個別路段的地點 ID,建議您使用 snapToRoads
或 nearestRoads
要求;無論要求哪一種都可以從單一呼叫傳回多個地點 ID。