Il metodo computeRoutes (REST) e il metodo ComputeRoutes (gRPC) restituiscono entrambi il percorso rappresentato da una polilinea come parte della risposta. Queste API restituiscono due tipi di polilinee:
Polilinea di base (predefinita), rappresenta un percorso, 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 di polilinee sensibili al traffico vengono fatturate alla tariffa di Routes Preferred. Scopri di più sulla fatturazione per l'API Routes. Per maggiori dettagli, consulta Configura la qualità della polilinea.
Per saperne di più sulle polilinee, consulta:
L'utilità interattiva di codifica delle polilinee ti 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 seguente.
Richiedi una polilinea di base per un percorso, una tratta o un passaggio
Una polilinea è rappresentata da un oggetto Polyline (REST) o Polyline (gRPC). Puoi restituire una polilinea nella risposta a livello di percorso, tratto e passaggio.
Specifica quale polilinea restituire utilizzando la maschera di campo della risposta:
A livello di percorso, restituisci una polilinea nella risposta includendo
routes.polylinenella maschera del campo della risposta.A livello di tratto, 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 tappa includendo
routes.legs.steps.polyline.
Ad esempio, per restituire una polilinea per l'intero percorso, per ogni tratto e per ogni passaggio 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 per il 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. Pertanto, la polilinea per la tratta e per il percorso è la stessa.
Se aggiungi un waypoint intermedio alla richiesta, il percorso restituito contiene due tappe:
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 tappe, ciascuna 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 sono specificati come valori di latitudine e longitudine, rappresentati in formato con rappresentazione in virgola mobile a precisione singola. Questo approccio funziona bene per i valori piccoli (che possono essere rappresentati con precisione), ma la precisione diminuisce man mano che i valori aumentano a causa di errori di arrotondamento della rappresentazione in virgola mobile.
Nel metodo computeRoutes (REST) e ComputeRoutes, questo è controllato da
polylineEncoding.Il numero di punti che compongono la polilinea
Più punti sono presenti, più la polilinea è uniforme (soprattutto nelle curve).
Nel metodo computeRoutes (REST) e ComputeRoutes, questo è controllato da
polylineQuality.
Configura il tipo di codifica della polilinea
Utilizza l'opzione di richiesta polylineEncoding per controllare il tipo di polilinea. La proprietà polylineEncoding controlla se la polilinea verrà codificata come ENCODED_POLYLINE (valore predefinito), ovvero verrà utilizzato il formato dell'algoritmo della polilinea codificata, o GEO_JSON_LINESTRING, ovvero verrà utilizzato il formato GeoJSON LineString.
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à della polilinea
polylineQuality specifica la qualità della polilinea come HIGH_QUALITY o OVERVIEW (valore predefinito). Con OVERVIEW, la polilinea viene composta utilizzando 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 sopra restituiscono tutti polilinee di base, ovvero polilinee senza informazioni sul traffico. Inoltre, puoi anche richiedere che la polilinea contenga informazioni sul traffico per il percorso e per 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 di inizio (inclusivo) e di fine (esclusivo) della polilinea.
Ad esempio, la seguente risposta mostra il traffico NORMAL tra i punti 2 e 4 della polilinea:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Per effettuare una richiesta di calcolo di una polilinea che tiene conto del traffico, imposta le seguenti proprietà nella richiesta:
Imposta il campo dell'array
extraComputationssuTRAFFIC_ON_POLYLINEper attivare il calcolo del traffico.Imposta
travelModesuDRIVEoTWO_WHEELER. Le richieste per qualsiasi altra modalità di viaggio restituiscono un errore.Specifica la preferenza di routing
TRAFFIC_AWAREoTRAFFIC_AWARE_OPTIMALnella richiesta. Per saperne di più, consulta Configura la qualità rispetto alla latenza.Imposta una maschera dei campi di risposta che specifica di restituire le proprietà della risposta:
A livello di percorso, restituisci tutte le informazioni di viaggio nella risposta includendo
routes.travelAdvisorynella maschera dei campi della risposta. Per restituire solo le informazioni sul traffico, specificaroutes.travelAdvisory.speedReadingIntervalsA livello di tratto, restituisci tutte le informazioni di viaggio nella risposta per ogni tratto 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 oggetto RouteLegTravelAdvisory (ogni tratto) e oggetto RouteTravelAdvisory (percorso).
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 nell'array è rappresentato da un oggetto SpeedReadingInterval (REST) o SpeedReadingInterval (gRPC).
Un oggetto SpeedReadingInterval include la lettura della velocità per un intervallo di percorso, ad esempio NORMAL, SLOW o TRAFFIC_JAM. L'intero array di oggetti copre l'intera polilinea del percorso senza sovrapposizioni. Il punto di partenza di un intervallo specificato è lo stesso del punto di arrivo dell'intervallo precedente.
Ogni intervallo è descritto da startPolylinePointIndex, endPolylinePointIndex e dalla categoria di velocità corrispondente. Tieni presente che l'assenza 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 erano le stesse dall'indice 2 all'indice 4.
Esegui il rendering di polilinee sensibili al traffico con Maps SDK
Ti consigliamo di visualizzare le polilinee sensibili al traffico sulla mappa utilizzando le varie funzionalità offerte dagli SDK Google Maps, tra cui colori personalizzati, tratti e pattern lungo i tratti della polilinea. Per maggiori dettagli sull'utilizzo delle polilinee, consulta Funzionalità delle polilinee per Android e Funzionalità delle polilinee per iOS.
Esempio di rendering di polilinee
Gli utenti di Maps SDK hanno la possibilità di definire una logica di mappatura personalizzata tra le categorie di velocità e gli schemi di rendering delle polilinee. Ad esempio, si potrebbe decidere di visualizzare la velocità "NORMALE" come una linea blu spessa sulla mappa, mentre la velocità "LENTA" potrebbe essere visualizzata come una linea arancione spessa.
I seguenti snippet aggiungono una polilinea blu spessa con segmenti geodetici da Melbourne a Perth. Per maggiori informazioni, consulta Personalizzazione degli aspetti (per Android) e Personalizza 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
Utilizza polilinee codificate con la funzionalità di ricerca lungo il percorso
Utilizza la Ricerca testuale (nuova) nell'API Places (nuova) per eseguire ricerche lungo un percorso calcolato. Passi la polilinea codificata di un percorso precalcolato da Compute Routes dell'API Routes alla richiesta di Ricerca testuale (novità). La risposta contiene quindi i luoghi che corrispondono ai criteri di ricerca e che si trovano anche vicino al percorso specificato. Per maggiori dettagli, consulta Cerca lungo un percorso.
Ad esempio, per restituire i bar lungo il percorso tra l'origine e la destinazione:
Node.js
const API_KEY = 'YOUR_API_KEY'; const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes'; const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); } async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; } init();