Il metodo computeRoutes (REST) e il ComputeRoutes (gRPC) restituiscono entrambi la route rappresentata da una polilinea come parte della risposta. Queste API restituiscono due tipi di polilinee:
Polilinea di base (impostazione predefinita), rappresenta una route, ma senza informazioni sul traffico incorporate nella polilinea. Le richieste che restituiscono una polilinea di base vengono fatturate alla tariffa di base di Routes. Scopri di più sulla fatturazione dell'API Routes.
Polilinea con informazioni sul traffico, contiene informazioni sulle condizioni del traffico lungo la route. 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 con informazioni sul traffico vengono fatturate alla tariffa preferenziale di Routes. Scopri di più sulla fatturazione per l'API Routes. Per maggiori dettagli, vedi Configurare la qualità della polilinea.
Per saperne di più sulle polilinee, vedi:
L'utilità interattiva di codifica delle polilinee 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 una route, 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 route, tratta e passaggio.
Specifica la polilinea da restituire utilizzando la maschera del campo di risposta:
A livello di route, restituisci una polilinea nella risposta includendo
routes.polylinenella maschera del campo di risposta.A livello di tratta, restituisci una polilinea nella risposta per ogni tratta della route includendo
routes.legs.polyline.A livello di passaggio, restituisci una polilinea nella risposta per ogni passaggio di tratta includendo
routes.legs.steps.polyline.
Ad esempio, per restituire una polilinea per l'intera route, per ogni tratta e per ogni passaggio di ogni tratta:
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 la route, per ogni tratta della route e per ogni passaggio della tratta:
{ "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, la route restituita contiene una sola tratta. Di conseguenza, la polilinea per la tratta e per la route è la stessa.
Se aggiungi un waypoint intermedio alla richiesta, la route restituita contiene due tratte:
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 tratte, ognuna con una polilinea univoca, e una polilinea per l'intera route:
{ "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, che sono rappresentati in formato a rappresentazione in virgola mobile a precisione singola. Questo funziona bene per i valori piccoli (che possono essere rappresentati con precisione), ma la precisione diminuisce man mano che i valori aumentano a causa degli errori di arrotondamento della rappresentazione in virgola mobile.
Nel computeRoutes (REST) e in ComputeRoutes, questo è controllato da
polylineEncoding.Il numero di punti che compongono la polilinea
Più punti ci sono, più liscia è la polilinea (soprattutto nelle curve).
Nel computeRoutes (REST) e in ComputeRoutes, questo è controllato da
polylineQuality.
Configurare il tipo di codifica della polilinea
Utilizza l'opzione di richiesta polylineEncoding per controllare il tipo di polilinea. La
polylineEncoding proprietà controlla se la polilinea verrà codificata come
ENCODED_POLYLINE (impostazione predefinita), il che significa che verrà utilizzato il formato
dell'algoritmo di polilinea codificata, o
GEO_JSON_LINESTRING, il che significa che 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'
Configurare la qualità della polilinea
polylineQuality specifica la qualità della polilinea come HIGH_QUALITY o OVERVIEW (impostazione predefinita). 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", ... }
Richiedere una polilinea con informazioni sul 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 la route e per ogni tratta della route.
Le polilinee con informazioni sul traffico contengono informazioni sulle condizioni del traffico lungo la route. 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 di inizio (inclusivo) e fine (esclusivo).
Ad esempio, la seguente risposta mostra il traffico NORMAL tra i punti della polilinea 2 e 4:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Per inviare una richiesta per calcolare una polilinea con informazioni sul traffico, imposta le seguenti proprietà nella richiesta:
Imposta il campo dell'array
extraComputationssuTRAFFIC_ON_POLYLINEper abilitare 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 Configurare la qualità rispetto alla latenza.Imposta una maschera del campo di risposta che specifichi di restituire le proprietà della risposta:
A livello di route, restituisci tutte le informazioni di viaggio nella risposta includendo
routes.travelAdvisorynella maschera del campo di 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 della route 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 con informazioni sul traffico
Nella risposta, i dati sul traffico vengono codificati nella polilinea e sono contenuti nel
travelAdvisory campo, di tipo
RouteLegTravelAdvisory (ogni tratta) e
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 sia RouteLegTravelAdvisory includono un campo array denominato speedReadingIntervals che contiene informazioni sulla velocità del traffico. Ogni
oggetto nell'array è rappresentato da un
SpeedReadingInterval (REST) o
SpeedReadingInterval
(gRPC).
Un oggetto SpeedReadingInterval include la lettura della velocità per un intervallo di route, ad esempio NORMAL, SLOW o TRAFFIC_JAM. L'intero array di oggetti copre l'intera polilinea della route senza sovrapposizioni. Il punto iniziale di un intervallo specificato è uguale al punto finale dell'intervallo precedente.
Ogni intervallo è descritto da startPolylinePointIndex, endPolylinePointIndex e dalla categoria di velocità corrispondente. Tieni presente che la
mancanza di un indice iniziale all'interno dell'intervallo corrisponde all'indice 0 in conformità
con le pratiche
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.
Eseguire il rendering delle polilinee con informazioni sul traffico con Maps SDK
Ti consigliamo di visualizzare le polilinee con informazioni sul traffico sulla mappa utilizzando le varie funzionalità offerte dagli SDK di Google Maps, tra cui colorazione, tratti e pattern personalizzati lungo i tratti della polilinea. Per maggiori dettagli sull'utilizzo delle polilinee, vedi Funzionalità delle polilinee per Android e Funzionalità delle polilinee per iOS.
Esempio di rendering della polilinea
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, potresti decidere di visualizzare la velocità "NORMAL" come una linea blu spessa sulla mappa, mentre la velocità "SLOW" potrebbe essere visualizzata come una linea arancione spessa.
I seguenti snippet aggiungono una polilinea blu spessa con segmenti geodetici da Melbourne a Perth. Per saperne di più, consulta Personalizzare l'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
Utilizzare le polilinee codificate con la ricerca lungo la route
Utilizza la ricerca testuale dell'API Places per cercare lungo una route calcolata. Trasmetti la polilinea codificata di una route precalcolata da Compute Routes dell'API Routes alla richiesta di ricerca testuale. La risposta contiene quindi i luoghi che corrispondono ai criteri di ricerca e che si trovano anche vicino alla route specificata. Per maggiori dettagli, vedi Cercare lungo una route.
Ad esempio, per restituire i bar lungo la route 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();