Questa pagina è stata tradotta dall'API Cloud Translation.

Richiedi polilinee percorso

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 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 in un determinato intervallo della polilinea. Le richieste di polilinee sensibili al traffico vengono fatturate alla tariffa preferita di Routes. Scopri di più sulla fatturazione per l'API Routes. Per i dettagli, consulta Configurare la qualità della polilinea

Per ulteriori informazioni sulle polilinee, vedi:

Informazioni concettuali sulle polilinee
L'utilità interattiva di codifica delle poliline ti consente di creare polilinee codificate in una UI o decodificare le polilinee per visualizzarle 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 presentano caratteri di escape JSON. Per visualizzare queste polilinee nell'Utilità encoder polilinea interattiva, devi prima rimuovere i caratteri di escape. Sono disponibili molte utilità per eseguire un'unescape JSON, come Freeformatter.

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, tratto e passo.

Specifica quale polilinea restituire utilizzando la maschera del campo di risposta:

A livello di route, restituisce una polilinea nella risposta includendo routes.polyline nella maschera del campo di risposta.
A livello di linea, restituisci una polilinea nella risposta per ogni tratto del percorso includendo routes.legs.polyline.

Nota: ogni tappa corrisponde alla corsa tra due tappe quando il valore via è falso per indicare una tappa del percorso. Ad esempio, un percorso senza tappe intermedie ha un solo tratto. Un percorso che include una tappa intermedia con una fermata ha due tratti. Un percorso che include un waypoint intermedio con via impostato su true ha un solo tratto.
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 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. Di conseguenza, la polilinea per il tratto e per il percorso è la stessa.

Se aggiungi una tappa intermedia 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 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à dei polilinea

La qualità di una polilinea può essere descritta nei seguenti termini:

La precisione con rappresentazione in virgola mobile dei punti

I punti sono specificati come valori di latitudine e longitudine, rappresentati in formato a virgola mobile a precisione singola. Questo approccio 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 con rappresentazione in virgola mobile.

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

Maggiore è il numero di punti, più fluida sarà la polilinea (soprattutto nelle curve).

Nel metodo computeRoutes (REST) e ComputeRoutes, questo è controllato da polylineQuality.

Configura tipo di codifica polilinea

Utilizza l'opzione di richiesta polylineEncoding per controllare il tipo di polilinea. La proprietà polylineEncoding consente di stabilire se la polilinea verrà codificata come ENCODED_POLYLINE (impostazione predefinita), ovvero verrà utilizzato il formato dell'algoritmo polilinea codificato o 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 Polyline

polylineQuality specifica la qualità della polilinea come HIGH_QUALITY o OVERVIEW (impostazione predefinita). 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",
  ...
}

Richiedere una polilinea sensibile al traffico

Gli esempi mostrati sopra restituiscono polilinee di base, ovvero le 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 (inclusivo) ed finale (esclusivo).

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 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 per 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 confronto tra qualità e latenza.
Imposta una maschera del campo di risposta che specifichi di restituire le proprietà della 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 tappa, 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 sul traffico sono codificati nella polilinea e sono contenuti nel campo travelAdvisory, di tipo RouteLegTravelAdvisory (ogni tratto) 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 oggetto SpeedReadingInterval (REST) o SpeedReadingInterval (gRPC).

Un oggetto SpeedReadingInterval include la lettura rapida per un intervallo di percorso, come 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 dai relativi startPolylinePointIndex, endPolylinePointIndex e dalla categoria di velocità corrispondente. Tieni presente che la mancanza di un indice iniziale nell'intervallo corrisponde all'indice 0 in base alle 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.

Rendering delle polilinee sensibili al traffico con Maps SDK

Ti consigliamo di mostrare le polilinee sensibili al traffico sulla mappa utilizzando le varie funzionalità offerte dagli SDK di Google Maps, tra cui colorazioni personalizzate, tratti e pattern lungo le tratti della polilinea. Per ulteriori dettagli sull'uso delle polilinee, consulta Funzionalità di Polyline per Android e Funzionalità di Polyline 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 polilinee. Ad esempio, si potrebbe decidere di visualizzare sulla mappa la velocità "NORMALE" come una spessa linea blu, mentre la velocità "SLOW" potrebbe essere visualizzata come una spessa linea arancione.

I seguenti snippet aggiungono una spessa polilinea blu con segmenti geodetici da Melbourne a Perth. Per ulteriori informazioni, vedi 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