Roads API restituisce il limite di velocità registrato per un determinato tratto di strada. Nel caso di tratti di strada con limiti di velocità variabili, viene restituito il limite di velocità predefinito per il tratto.
L'accuratezza dei dati sul limite di velocità restituiti da Roads API non può essere garantita. I dati sui limiti di velocità forniti non sono in tempo reale e potrebbero essere stimati, imprecisi, incompleti e/o obsoleti. Consulta i dettagli della copertura per visualizzare le regioni in cui sono disponibili i dati sui limiti di velocità.
Richieste
Una richiesta di limiti di velocità deve essere inviata tramite HTTPS e ha il formato seguente:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
Utilizzo dei parametri
Parametri obbligatori
- Parametro
path
oplaceId
.path
: un elenco di massimo 100 coppie di latitudine/longitudine che rappresentano un percorso. I valori di latitudine e longitudine devono essere separati da virgole. Le coppie latitudine/longitudine devono essere separate dal carattere barra verticale: "|". Quando specifichi il parametropath
, l'API aggancia innanzitutto il percorso alla strada più probabile percorsa da un veicolo (come per la richiestasnapToRoads
), poi determina il limite di velocità per il tratto di strada pertinente. Se non vuoi che l'API agganci il percorso, devi passare un parametroplaceId
come spiegato di seguito. L'esempio seguente mostra il parametropath
con tre coppie latitudine/longitudine:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
.placeId
: gli ID luogo che rappresentano uno o più tratti di strada. Assicurati che ogni ID luogo si riferisca a un tratto di strada e non a un tipo di luogo diverso. Puoi trasmettere fino a 100 ID luogo con ogni richiesta. L'API non esegue l'agganciamento della strada sugli ID luogo forniti. La risposta include un limite di velocità per ogni ID luogo nella richiesta. Puoi inviare una richiestasnapToRoads
onearestRoads
per trovare gli ID luogo pertinenti e poi fornirli come input nella richiestaspeedLimits
. L'esempio seguente mostra il parametroplaceId
con due ID luogo:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
: chiave API della tua applicazione. L'applicazione deve identificarsi ogni volta che invia una richiesta a Roads API includendo una chiave API in ogni richiesta. Scopri come ottenere una chiave.
Parametri facoltativi
units
- Indica se restituire i limiti di velocità in chilometri o miglia orarie. Questo valore può essere impostato suKPH
oMPH
. Il valore predefinito èKPH
.
Risposte
In una risposta speedLimits
potrebbero essere presenti i seguenti elementi:
speedLimits
: array di metadati di strade. Ogni elemento è costituito dai seguenti campi:placeId
: un identificatore univoco di un luogo. Tutti gli ID luogo restituiti da Roads API corrisponderanno ai tratti di strada.speedLimit
: il limite di velocità per il tratto di strada in questione.units
: restituisceKPH
oMPH
.
snappedPoints
: una serie di punti agganciati. Questo array è presente solo se la richiesta conteneva un parametropath
. Ogni punto è costituito dai seguenti campi:location
: contiene un valorelatitude
e un valorelongitude
.originalIndex
: un numero intero che indica il valore corrispondente nella richiesta originale. Ogni valore nella richiesta deve essere mappato a un valore agganciato nella risposta. Questi valori sono indicizzati da0
, quindi un punto con unoriginalIndex
di4
sarà il valore agganciato della quinta latitudine/longitudine passata al parametropath
.placeId
: un identificatore univoco di un luogo. Tutti gli ID luogo restituiti da Roads API corrisponderanno ai tratti di strada.placeId
può essere trasmesso in una richiesta sui limiti di velocità per determinare il limite di velocità lungo quel tratto di strada.
warning_message
: una stringa contenente un avviso visibile all'utente.
Esempio di richiesta mediante un percorso
Questa richiesta restituisce il limite di velocità per ogni tratto di strada più vicino alle coppie di latitudine/longitudine specificate in un percorso che attraversa il ponte Vasco da Gama a Lisbona, in Portogallo.
Richiedi
https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY
Risposta
{ 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." }
Osserva il messaggio di avviso per la sparsità dei punti nella risposta precedente. Se richiedi limiti di velocità per i tratti di strada più vicini in punti arbitrari, devi chiamare speedLimits
utilizzando gli ID luogo recuperati dall'endpoint di nearestRoads
.
Esempio di richiesta utilizzando gli ID luogo
Invece di utilizzare le coppie latitudine/longitudine, puoi trasmettere gli ID luogo dei segmenti di strada. Ti consigliamo di ottenere gli ID luogo per i tratti di strada utilizzando le richieste snapToRoads
o nearestRoads
. Quando trasmetti gli ID luogo, l'API restituisce il limite di velocità per il tratto di strada rappresentato da ciascun ID luogo. L'API
non applica alcun aggancio stradale agli ID luogo forniti.
L'esempio seguente richiede i limiti di velocità per alcuni tratti di strada che attraversano il ponte Vasco da Gama a Lisbona, in Portogallo.
Richiedi
https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY
Risposta
{ "speedLimits": [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ] }
Suggerimenti sull'utilizzo
Per ridurre al minimo il volume delle chiamate al servizio Limite di velocità, ti consigliamo di campionare le posizioni degli asset a intervalli di 5-15 minuti (il valore esatto dipende dalla velocità di spostamento dell'asset). Se un asset è stazionario, è sufficiente un solo campione di località (non è necessario effettuare più chiamate).
Per ridurre al minimo la latenza complessiva, ti consigliamo di chiamare il servizio Limite di velocità dopo aver accumulato dei dati, anziché chiamare l'API ogni volta che viene ricevuta la posizione di un asset mobile.
Perché mancano alcuni o tutti i limiti di velocità?
La causa più comune della mancanza di speedLimits
è la richiesta del limite di velocità di un luogo che non è un tratto di strada.
L'esempio precedente utilizza il ponte Vasco da Gama per illustrare i concetti, che supporta la strada E90 che attraversa il Rio Tejo. Il ponte
stesso ha un ID luogo di ChIJUzt97ZEwGQ0RM1JzQfqoDtU. Il primo tratto di strada nella risposta precedente fa parte della strada E90 e ha l'ID luogo ChIJX12duJAwGQ0Ra0d4Oi4jOGE. Nella richiesta di esempio, se sostituisci l'ID luogo della strada con l'ID posizione del ponte, nella risposta ci saranno solo due limiti di velocità nell'array speedLimits
perché l'ID posizione del ponte non fa riferimento a un singolo segmento di strada. Inoltre, se nessuno degli ID luogo è relativo a tratti di strada, la risposta non conterrà limiti di velocità.
Quando invii richieste di limiti di velocità utilizzando gli ID luogo, assicurati che ogni ID luogo faccia riferimento a un tratto di strada e non a un tipo di luogo diverso. Il modo migliore per recuperare gli ID luogo per i singoli tratti di strada è utilizzare richieste snapToRoads
o nearestRoads
, entrambe possono restituire più ID luogo da una singola chiamata.