Il metodo computeRoutes (REST) e il metodo ComputeRoutes (gRPC) restituiscono entrambi la route rappresentata da una polilinea come parte della risposta. Queste API restituiscono due tipi di polilinee:
Polilinea di base (predefinita), rappresenta una route ma senza informazioni sul traffico incorporate nella polilinea. Le richieste che restituiscono una polilinea di base vengono fatturate alla tariffa Routes Basic. Scopri di più sulla fatturazione per l'API Routes.
Polilinea sensibile al traffico: contiene informazioni sulle condizioni del traffico lungo il percorso. Le condizioni del traffico sono espresse in termini di categorie di velocità (
NORMAL
,SLOW
,TRAFFIC_JAM
) applicabili a un determinato intervallo della polilinea. Le richieste per le polilinee sensibili al traffico vengono fatturate alla tariffa preferita per le route. Scopri di più sulla fatturazione per l'API Routes. Per maggiori dettagli, consulta Configurare la qualità della polilinea
Per ulteriori informazioni sulle polilinee, vedi:
L'utilità interattiva Polyline Encoder consente di creare polilinee codificate in un'interfaccia utente o di decodificare le polilinee da visualizzare su una mappa. Ad esempio, utilizza questa utilità per decodificare una polilinea creata dal codice riportato di seguito.
Richiedere una polilinea di base per un percorso, una tratta o un passo
Una polilinea è rappresentata da un oggetto Polyline (REST) o Polyline (gRPC). Puoi restituire una polilinea nella risposta a livello di percorso, gamba e passo.
Specifica la polilinea da restituire utilizzando la maschera del campo di risposta:
A livello di route, restituisci una polilinea nella risposta includendo
routes.polyline
nella maschera del campo della risposta.A livello di gamba, restituisci una polilinea nella risposta per ogni tratto del percorso includendo
routes.legs.polyline
.A livello di passaggio, restituisci una polilinea nella risposta per ogni passaggio della gamba includendo
routes.legs.steps.polyline
.
Ad esempio, per restituire una polilinea per l'intero percorso, per ogni tratto e per ogni passo di ogni tratto:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Questa richiesta restituisce la seguente risposta, che include la polilinea del percorso, per ogni tratto del percorso e per ogni passaggio del tratto:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } }, "steps": [ { "polyline": { "encodedPolyline": "kclcF...@sC@YIOKI" } }, { "polyline": { "encodedPolyline": "wblcF~...SZSF_@?" } }, ... ], "distanceMeters": 56901, "duration": "2420s", "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } } ] }
Poiché questa richiesta contiene solo un'origine e una destinazione, il percorso restituito contiene solo un tratto. Di conseguenza, la polilinea per il tratto e per il percorso sono la stessa.
Se aggiungi un waypoint intermedio alla richiesta, il percorso restituito contiene due segmenti:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "intermediates": [ { "address": "450 Serra Mall, Stanford, CA 94305, USA"}, ], "travelMode": "DRIVE", }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Questa richiesta restituisce due tratti, ognuno con una polilinea univoca e una polilinea per l'intero percorso:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG" } "steps": [ { "polyline": { "encodedPolyline": "kclcFfqch...YIOKI" } }, ... }, { "polyline": { "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G" } "steps": [ { "polyline": { "encodedPolyline": "uypeFbo`jVgJq...PoBiC" } }, ... } ], "distanceMeters": 68403, "duration": "3759s", "polyline": { "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE" } } ] }
Qualità della polilinea
La qualità di una polilinea può essere descritta nei seguenti termini:
La precisione in virgola mobile dei punti
I punti vengono specificati come valori di latitudine e longitudine, rappresentati nel formato in virgola mobile a precisione singola. Questo approccio funziona bene per i valori piccoli (che possono essere rappresentati con precisione), ma la precisione diminuisce all'aumentare dei valori a causa degli errori di arrotondamento in virgola mobile.
Nel metodo computeRoutes (REST) e ComputeRoutes, questo metodo è controllato da
polylineEncoding
.Il numero di punti che compongono la polilinea
Maggiore è il numero di punti presenti, più liscia è la polilinea (soprattutto nelle curve).
Nel metodo computeRoutes (REST) e ComputeRoutes, questo metodo è controllato da
polylineQuality
.
Configura tipo di codifica polilinea
Utilizza l'opzione di richiesta polylineEncoding
per controllare il tipo di polilinea.
La proprietà polylineEncoding
controlla se la polilinea sarà codificata come
ENCODED_POLYLINE
(impostazione predefinita), il che significa che verrà utilizzato il
Formato algoritmo Polilinea codificato
oppure GEO_JSON_LINESTRING
, che indica che verrà utilizzato il
formato LineString GeoJSON.
Ad esempio, nel corpo della richiesta:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "polylineEncoding": "ENCODED_POLYLINE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Configura la qualità di Poyline
polylineQuality
specifica la qualità della polilinea come HIGH_QUALITY
o OVERVIEW
(valore predefinito). Con OVERVIEW
, la polilinea è composta da un numero ridotto di punti e ha una latenza di richiesta inferiore rispetto a HIGH_QUALITY
.
Ad esempio, nel corpo della richiesta:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE", "polylineQuality": "HIGH_QUALITY", "polylineEncoding": "ENCODED_POLYLINE", "departureTime": "2023-10-15T15:01:23.045123456Z", ... }
Richiedi una polilinea sensibile al traffico
Gli esempi mostrati in alto restituiscono polilinee di base, ovvero polilinee senza informazioni sul traffico. Inoltre, puoi richiedere che la polilinea contenga informazioni sul traffico relative al percorso e a ogni tratto del percorso.
Le polilinee sensibili al traffico contengono informazioni sulle condizioni del traffico lungo il percorso. Le condizioni del traffico sono espresse in termini di categorie di velocità (NORMAL
, SLOW
, TRAFFIC_JAM
) per un determinato intervallo della polilinea di risposta. Gli intervalli sono definiti dagli indici dei punti della polilinea iniziale (inclusiva) e finale (esclusiva).
Ad esempio, la seguente risposta mostra il traffico NORMAL
tra i punti della polilinea 2 e 4:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Per effettuare una richiesta di calcolo di una polilinea sensibile al traffico, imposta le seguenti proprietà nella richiesta:
Imposta il campo array
extraComputations
suTRAFFIC_ON_POLYLINE
per abilitare il calcolo del traffico.Imposta
travelMode
suDRIVE
oTWO_WHEELER
. Le richieste relative a qualsiasi altra modalità di viaggio restituiscono un errore.Specifica la preferenza di routing
TRAFFIC_AWARE
oTRAFFIC_AWARE_OPTIMAL
nella richiesta. Per ulteriori informazioni, consulta Configurare qualità e latenza.Imposta una maschera del campo della risposta che specifichi di restituire le proprietà della risposta:
A livello di route, restituisci tutte le informazioni di viaggio nella risposta, includendo
routes.travelAdvisory
nella maschera del campo della risposta. Per restituire solo le informazioni sul traffico, specificaroutes.travelAdvisory.speedReadingIntervals
A livello di tratta, restituisci tutte le informazioni di viaggio nella risposta per ogni tratta del percorso includendo
routes.legs.travelAdvisory
. Per restituire solo le informazioni sul traffico, specificaroutes.legs.travelAdvisory.speedReadingIntervals
.
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "extraComputations": ["TRAFFIC_ON_POLYLINE"], "routingPreference": "TRAFFIC_AWARE_OPTIMAL" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Esempio di risposta per una polilinea sensibile al traffico
Nella risposta, i dati sul traffico sono codificati nella polilinea e sono contenuti nel campo travelAdvisory
, di tipo RouteLegTravelAdvisory (ogni tratto) e nell'oggetto RouteTravelAdvisory (route).
Ad esempio:
{ "routes": [ { "legs": { "polyline": { "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD" }, // Traffic data for the leg. "travelAdvisory": { "speedReadingIntervals": [ { "endPolylinePointIndex": 1, "speed": "NORMAL" }, { "startPolylinePointIndex": 1, "endPolylinePointIndex": 2, "speed": "SLOW" }, { "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" } ] } }, "polyline": { "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD" }, // Traffic data for the route. "travelAdvisory": { "speedReadingIntervals": [ { "endPolylinePointIndex": 1, "speed": "NORMAL" }, { "startPolylinePointIndex": 1, "endPolylinePointIndex": 2, "speed": "SLOW" }, { "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" } ] } } ] }
Sia RouteTravelAdvisory
che RouteLegTravelAdvisory
includono un campo array chiamato speedReadingIntervals
che contiene informazioni sulla velocità del traffico. Ogni oggetto dell'array è rappresentato da un oggetto SpeedReadingInterval (REST) o SpeedReadingInterval (gRPC).
Un oggetto SpeedReadingInterval
include la lettura della velocità per un intervallo di route, come NORMAL
, SLOW
o TRAFFIC_JAM
. L'intera gamma di oggetti copre
l'intera polilinea del percorso senza sovrapposizioni. Il punto iniziale di un intervallo specificato corrisponde al punto finale dell'intervallo precedente.
Ogni intervallo è descritto dai relativi startPolylinePointIndex
,
endPolylinePointIndex
e dalla categoria di velocità corrispondente.
Nota che la mancanza di un indice iniziale all'interno dell'intervallo corrisponde all'indice 0 in conformità con le pratiche di proto3.
I valori startPolylinePointIndex
e endPolylinePointIndex
non sono sempre consecutivi. Ad esempio:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
In questo caso, le condizioni del traffico dall'indice 2 all'indice 4 erano le stesse.
Esegui il rendering delle polilinee sensibili al traffico con Maps SDK
Ti consigliamo di visualizzare sulla mappa le polilinee sensibili al traffico utilizzando le varie funzionalità offerte dagli SDK di Google Maps, tra cui colorazioni, tratti e motivi personalizzati lungo i tratti delle polilinee. Per maggiori dettagli sull'utilizzo delle polilinee, consulta Funzionalità Polilinea per Android e Funzionalità Polilinea per iOS.
Esempio di rendering Polilinea
Gli utenti di Maps SDK hanno l'opportunità di definire una logica di mappatura personalizzata tra le categorie di velocità e gli schemi di rendering delle poliline. Ad esempio, si potrebbe decidere di visualizzare la velocità "NORMAL" sotto forma di linea blu spessa sulla mappa, mentre la velocità "LENTA" potrebbe essere visualizzata come una linea spessa arancione.
I seguenti snippet aggiungono una spessa polilinea blu con segmenti geodetici da Melbourne a Perth. Per ulteriori informazioni, consulta Personalizzazione dell'aspetto (per Android) e Personalizzare la polilinea (per iOS).
Android
Java
Polyline line = map.addPolyline(new PolylineOptions() .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734)) .width(25) .color(Color.BLUE) .geodesic(true));
Kotlin
val line: Polyline = map.addPolyline( PolylineOptions() .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734)) .width(25f) .color(Color.BLUE) .geodesic(true) )
iOS
Objective-C
GMSMutablePath *path = [GMSMutablePath path]; [path addLatitude:-37.81319 longitude:144.96298]; [path addLatitude:-31.95285 longitude:115.85734]; GMSPolyline *polyline = [GMSPolyline polylineWithPath:path]; polyline.strokeWidth = 10.f; polyline.strokeColor = .blue; polyline.geodesic = YES; polyline.map = mapView;
Swift
let path = GMSMutablePath() path.addLatitude(-37.81319, longitude: 144.96298) path.addLatitude(-31.95285, longitude: 115.85734) let polyline = GMSPolyline(path: path) polyline.strokeWidth = 10.0 polyline.geodesic = true polyline.map = mapView