Roads API restituisce il limite di velocità registrato per un determinato segmento 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 sui limiti di velocità restituiti da Roads API non può essere garantita. I dati relativi al limite di velocità forniti non sono in tempo reale e potrebbero essere stimati, imprecisi, incompleti e/o obsoleti. Consulta i dettagli sulla 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 seguente formato:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
Utilizzo dei parametri
Parametri obbligatori
- Un parametro
path
oplaceId
.path
: un elenco di massimo 100 coppie latitudine/longitudine che rappresentano un percorso. I valori di latitudine e longitudine devono essere separati da virgole. Le coppie di latitudine/longitudine devono essere separate dal carattere barra verticale: "|". Quando fornisci il parametropath
, l'API prima aggancia 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 di 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 stradali. Assicurati che ogni ID luogo si riferisca a un tratto stradale e non a un tipo di luogo diverso. Puoi trasmettere fino a 100 ID luogo con ogni richiesta. L'API non esegue lo snapping delle strade 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, quindi fornirli come input alla richiestaspeedLimits
. L'esempio seguente mostra il parametroplaceId
con due ID luogo:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
: la chiave API della tua applicazione. La tua applicazione deve identificarsi ogni volta che invia una richiesta al servizioRoads 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 all'ora. Può essere impostato suKPH
oMPH
. Il valore predefinito èKPH
.
Risposte
I seguenti elementi possono essere presenti in una risposta speedLimits
:
speedLimits
: un array di metadati relativi alla strada. Ogni elemento è costituito dai seguenti campi:placeId
: un identificatore univoco per un luogo. Tutti gli ID luogo restituiti da Roads API corrisponderanno ai tratti stradali.speedLimit
: il limite di velocità per quel tratto di strada.units
: restituisceKPH
oMPH
.
snappedPoints
: un array di punti agganciati. Questo array è presente solo se la richiesta conteneva un parametropath
. Ogni punto è costituito dai seguenti campi:location
: contiene un valorelatitude
elongitude
.originalIndex
: un numero intero che indica il valore corrispondente nella richiesta originale. Ogni valore nella richiesta deve essere mappato a un valore snappato nella risposta. Questi valori sono indicizzati da0
, pertanto un punto con un valoreoriginalIndex
pari a4
sarà il valore agganciato della quinta latitudine/longitudine passata al parametropath
.placeId
: un identificatore univoco per un luogo. Tutti gli ID luogo restituiti da Roads API corrisponderanno ai tratti stradali.placeId
può essere passato in una richiesta di 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 che utilizza un percorso
Questa richiesta recupera 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." }
Nota il messaggio di avviso relativo alla scarsità di punti nella risposta sopra riportata. Se
richiedi i limiti di velocità per i tratti stradali più vicini in punti arbitrari,
devi chiamare speedLimits
con gli ID luogo recuperati dall'endpoint
nearestRoads
.
Richiesta di esempio che utilizza gli ID luogo
Anziché utilizzare coppie di latitudine/longitudine, puoi passare gli ID dei luoghi dei tratti di strada. Ti consigliamo di ottenere gli ID luogo per i tratti stradali utilizzando
le richieste snapToRoads
o nearestRoads
. Quando passi 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 allineamento stradale agli ID luogo forniti.
L'esempio seguente richiede i limiti di velocità per alcuni dei 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" } ] }
Consigli per l'utilizzo
Per ridurre al minimo il volume di chiamate al servizio di limiti di velocità, ti consigliamo di eseguire il campionamento delle posizioni delle risorse a intervalli di 5-15 minuti (il valore esatto dipende dalla velocità con cui si sposta una risorsa). Se un asset è statico, è sufficiente un singolo sample di posizione (non è necessario effettuare più chiamate).
Per ridurre al minimo la latenza complessiva, ti consigliamo di chiamare il servizio Limite di velocità dopo aver accumulato alcuni dati, anziché chiamare l'API ogni volta che viene ricevuta la posizione di una risorsa mobile.
Perché mancano alcuni/tutti i limiti di velocità?
La causa più comune della mancata presenza di speedLimits
è la richiesta del limite di velocità
di un luogo che non è un tratto di strada.
L'esempio riportato sopra utilizza il ponte Vasco da Gama per illustrare i concetti. Il ponte supporta la strada E90 che attraversa il fiume Tejo. Il ponte stesso ha un ID posizione di ChIJUzt97ZEwGQ0RM1JzQfqoDtU. Il primo tratto di strada
nella risposta sopra riportata fa parte della strada E90 e ha un ID luogo di
ChIJX12duJAwGQ0Ra0d4Oi4jOGE. Nella richiesta di esempio, se sostituisci l'ID luogo della strada con l'ID luogo del ponte, nella risposta saranno presenti solo due limiti di velocità nell'array speedLimits
perché l'ID luogo del ponte non fa riferimento a un singolo tratto di strada. Inoltre, se nessuno degli ID luogo riguarda segmenti stradali, la risposta non conterrà limiti di velocità.
Quando invii richieste di limiti di velocità utilizzando gli ID luogo, assicurati che ogni ID luogo si riferisca a un tratto di strada e non a un tipo di luogo diverso. Gli ID luogo per singoli tratti stradali sono ideali per essere recuperati utilizzando le richieste snapToRoads
o nearestRoads
, che possono restituire più ID luogo da una singola chiamata.