Questa pagina è stata tradotta dall'API Cloud Translation.

Richiedi polilinee percorso

La codifica Polyline è un algoritmo di compressione con perdita che consente di archiviare una serie di coordinate, ad esempio una route, come una singola stringa. Il processo di codifica converte un valore binario in una serie di codici carattere per i caratteri ASCII utilizzando lo schema di codifica Base64. Per una descrizione completa del processo di codifica, consulta la sezione Formato dell'algoritmo della polilinea codificata.

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 di Route di base. Scopri di più sulla fatturazione per l'API Routes.
Polilinea sensibile al traffico, che 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 su un determinato intervallo della polilinea. Le richieste di 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:

Configura qualità e latenza per informazioni sulla configurazione della qualità della polilinea.
Formato algoritmo polilinea codificato descrive l'algoritmo per la codifica di una polilinea.
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.

Nota: i caratteri speciali nelle polilinee restituite dall'API REST sono caratteri di escape JSON. Per visualizzare queste polilinee nell'utilità di codifica Polyline interattiva, devi prima rimuovere i caratteri di escape. Sono disponibili molte utilità per eseguire l'annullamento di una sequenza di caratteri JSON, come Freeformatter.

Richiedere una polilinea di base per un percorso, un tratto o un passo

Una polilinea è rappresentata da un oggetto Polyline (REST) o Polyline (gRPC). Puoi restituire una polilinea nella risposta a livello di percorso, tratto 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 di risposta.
A livello di gamba, restituisci una polilinea nella risposta per ogni tratto del percorso includendo routes.legs.polyline.

Nota: ogni tratto corrisponde alla corsa tra due tappe quando via è false per il Waypoint al fine di indicare una fermata lungo il percorso. Ad esempio, un percorso senza tappe intermedie ha una sola tratta. Un percorso che include un tappa intermedia con una fermata ha due tappe. Un percorso che include un passaggio intermedio con via impostato su true ha una tratta.
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 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 del percorso, di ogni tratto del percorso e di 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, il percorso restituito contiene solo una singola tratta. Pertanto, la polilinea per il tratto e per il percorso sono la stessa.

Se aggiungi un Waypoint intermedio alla richiesta, il percorso restituito conterrà due parti:

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 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"
      }
    }
  ]
}

Configura tipo di codifica polilinea

Utilizza l'opzione di richiesta polylineEncoding per controllare il tipo di polilinea. La proprietà polylineEncoding specifica come codificare la polilinea come ENCODED_POLYLINE (valore predefinito), ovvero come utilizzare l'algoritmo di codifica delle polilinea, o GEO_JSON_LINESTRING, che utilizza 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'

Richiedi una polilinea sensibile al traffico

Gli esempi mostrati sopra restituiscono polilinee di base, ovvero polilinee senza informazioni sul traffico. Inoltre, puoi 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 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 per calcolare una polilinea sensibile al traffico, imposta le seguenti proprietà nella richiesta:

Imposta il campo array extraComputations su TRAFFIC_ON_POLYLINE per abilitare 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 qualità e latenza.
Imposta una maschera per il 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 di risposta. Per restituire solo le informazioni sul traffico, specifica routes.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, 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'

Esempio di risposta per una polilinea sensibile al traffico

Nella risposta, i dati di traffico sono codificati nella polilinea e sono contenuti nel campo travelAdvisory, di tipo RouteLegTravelAdvisory per l'oggetto (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 sia RouteLegTravelAdvisory includono un campo array denominato 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, come NORMAL, SLOW o TRAFFIC_JAM. L'intera gamma 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 dai rispettivi valori startPolylinePointIndex, endPolylinePointIndex e dalla categoria di velocità corrispondente. Tieni presente che la mancanza di un indice iniziale nell'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 uguali dall'indice 2 all'indice 4.

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 le pagine Funzionalità Polyline per Android e Funzionalità Polyline per iOS.

Esempio di rendering Polyline

Gli utenti dell'SDK di Maps hanno l'opportunità di definire una logica di mappatura personalizzata tra le categorie di velocità e gli schemi di rendering delle polilinea. 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 spessa arancione, ad esempio.

I seguenti snippet aggiungono una spessa polilinea blu con segmenti geodetici da Melbourne a Perth. Per maggiori informazioni, vedi Personalizzazione dell'aspetto (per Android) e Personalizzare l'aspetto di 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