Questa pagina è stata tradotta dall'API Cloud Translation.

Richiedi polilinee percorso

Il metodo computeRoutes (REST) e il metodo ComputeRoutes (gRPC) restituiscono entrambi il percorso rappresentato da un polilinea nell'ambito 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 un polilinea di base vengono fatturate alla tariffa di base per i percorsi. 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 del polilinea. Le richieste di polilinee sensibili al traffico vengono fatturate alla tariffa Route Preferred. Scopri di più sulla fatturazione per l'API Routes. Per maggiori dettagli, consulta Configurare la qualità dei polilinee

Per saperne di più sulle polilinee, consulta:

Informazioni concettuali su polilinee
L'utilità di codifica polilinee interattiva 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.

Nota: i caratteri speciali nei polilinee restituiti dall'API REST sono sottoposti a evocazione JSON. Per visualizzare queste polilinee nell'utilità Interactive Polyline Encoder, devi prima eseguire lo scollegamento. Esistono molte utilità disponibili per eseguire uno scollegamento JSON, come Freeformatter.

Richiedere una polilinea di base per un percorso, una tappa 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 il polilinea da restituire utilizzando la maschera del campo di risposta:

A livello di itinerario, restituisci un polilinea nella risposta includendo routes.polyline nella maschera del campo della risposta.
A livello di tratto, restituisci un polilinea nella risposta per ogni tratto del percorso includendo routes.legs.polyline.

Nota: ogni tratto corrisponde al tragitto tra due waypoint quando via è false per indicare una fermata sul percorso. Ad esempio, un itinerario senza waypoint intermedi ha un solo tratto. Un percorso che include un waypoint intermedio con una fermata ha due tratti. Un percorso che include un waypoint intermedio con via impostato su true ha un tratto.
A livello di passaggio, restituisci un polilinea nella risposta per ogni passaggio della tratta includendo routes.legs.steps.polyline.

Ad esempio, per restituire un 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 il 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 un solo tratto. Pertanto, la polilinea per la tratta e per il percorso è la stessa.

Se aggiungi un punto di passaggio intermedio alla richiesta, il percorso restituito contiene due tratti:

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, ciascuno con un polilinea univoco, e un 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 un 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 a virgola mobile con precisione singola. Questo funziona bene per valori piccoli (che possono essere rappresentati con precisione), ma la precisione diminuisce con l'aumento dei valori a causa di errori di arrotondamento a virgola mobile.

Nel metodo computeRoutes (REST) e ComputeRoutes, questo viene controllato da polylineEncoding.
Il numero di punti che compongono il polilinea

Più punti sono presenti, più liscia sarà la polilinea (soprattutto nelle curve).

Nel metodo computeRoutes (REST) e ComputeRoutes, questo viene 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 il polilinea verrà codificato come ENCODED_POLYLINE (valore predefinito), il che significa che verrà utilizzato il formato dell'algoritmo polilinea codificato, oppure come GEO_JSON_LINESTRING, il che significa 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à della polilinea

polylineQuality specifica la qualità del polilinea come HIGH_QUALITY o OVERVIEW (valore predefinito). Con OVERVIEW, il polilinea è composto utilizzando un numero ridotto di punti e ha una latenza di richiesta inferiore 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 che tenga conto del traffico

Gli esempi riportati sopra restituiscono tutti polilinee di base, ovvero polilinee senza informazioni sul traffico. Inoltre, puoi anche richiedere che il polilinea contenga informazioni sul traffico per il percorso e per ogni tratto del percorso.

I 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 del polilinea di risposta. Gli intervalli sono definiti dagli indici dei punti iniziale (incluso) e finale (escluso) del polilinea.

Ad esempio, la seguente risposta mostra il traffico NORMAL tra i punti 2 e 4 del polilinea:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Per effettuare una richiesta di calcolo di un polilinea che tenga conto del traffico, imposta le seguenti proprietà nella richiesta:

Imposta il campo dell'array extraComputations su TRAFFIC_ON_POLYLINE per attivare il calcolo del traffico.
Imposta travelMode su DRIVE o TWO_WHEELER. Le richieste di qualsiasi altra modalità di viaggio restituiscono un errore.
Specifica la preferenza di routing TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL nella richiesta. Per ulteriori informazioni, consulta Configurare la qualità rispetto alla latenza.
Imposta una maschera di campo di risposta che specifica di restituire le proprietà di risposta:
- A livello di percorso, restituisci tutte le informazioni di viaggio nella risposta includendo routes.travelAdvisory nella maschera del campo di risposta. Per restituire solo le informazioni sul traffico, specifica routes.travelAdvisory.speedReadingIntervals
- A 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, specifica routes.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'

Risposta di esempio per un polilinea sensibile al traffico

Nella risposta, i dati sul traffico sono codificati nel polilinea e sono contenuti nel campo travelAdvisory, di tipo RouteLegTravelAdvisory (ogni tratto) e 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 SpeedReadingInterval (REST) o SpeedReadingInterval (gRPC).

Un oggetto SpeedReadingInterval include la lettura della velocità per un intervallo di percorso, come NORMAL, SLOW o TRAFFIC_JAM. L'intero array di oggetti copre l'intero polilinea del percorso senza sovrapposizioni. Il punto di inizio di un intervallo specificato corrisponde al punto di fine dell'intervallo precedente.

Ogni intervallo è descritto dal valore startPolylinePointIndex, endPolylinePointIndex e dalla categoria di velocità corrispondente. Tieni presente che l'assenza dell'indice di inizio all'interno dell'intervallo corrisponde all'indice 0 in conformità con le norme 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.

Eseguire il rendering di polilinee che tengono conto del traffico con l'SDK Maps

Ti consigliamo di visualizzare le polilinee sensibili al traffico sulla mappa utilizzando le varie funzionalità offerte dagli SDK di Google Maps, tra cui colorazioni, tratti e motivi personalizzati lungo i tratti delle polilinee. Per ulteriori dettagli sull'utilizzo delle polilinee, consulta Elementi polilinea per Android e Elementi polilinea per iOS.

Esempio di rendering di una 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, si potrebbe decidere di mostrare la velocità "NORMALE" con una linea blu spessa sulla mappa, mentre la velocità "LENTE" potrebbe essere visualizzata con una linea arancione spessa.

I seguenti snippet aggiungono un polilinea blu spesso con segmenti geodetici da Melbourne a Perth. Per saperne di più, consulta Personalizzare l'aspetto (per Android) e Personalizzare il tratto 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