Richiedi polilinee percorso

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

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:

  • Polineline 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 Route di base. Scopri di più sulla fatturazione per l'API Routes.

  • Polineline 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 di polilinea. Le richieste di polilinee sensibili al traffico vengono fatturate alla tariffa Preferred Routes. Scopri di più sulla fatturazione per l'API Routes.

Per ulteriori informazioni sulle polilinee, vedi:

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

Una polilinea è rappresentata da un oggetto Polyline (REST) o Polyline (gRPC). Puoi restituire una polilinea nella risposta a livello di percorso, gamba e passo.

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

  • A livello di percorso, 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 tratta del percorso includendo routes.legs.polyline.

  • 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 gamba e per ogni passaggio di ogni gamba:

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 suo passaggio:

{
  "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 la gamba e per il percorso sono le stesse.

Se aggiungi un punto di via 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 vie, 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"
      }
    }
  ]
}

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 (impostazione predefinita), ovvero utilizzando l'algoritmo di codifica della polilinea, oppure GEO_JSON_LINESTRING, nel senso che utilizza il formato LineString LineJSON.

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 tutte le 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 intervallo specifico di polilinea di risposta. Gli intervalli sono definiti dagli indici dei punti polilinea di partenza (inclusi) e finali (esclusivi).

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

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

Per effettuare una richiesta di calcolo di una polilinea sensibile al traffico, imposta le seguenti proprietà nella richiesta:

  • Imposta il campo dell'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 la pagina Confronto tra qualità e latenza.

  • Imposta una maschera nel 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 gamba, 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'

Risposta di esempio 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 gamba) e dell'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 di 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 veloce di 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. Nota che la mancanza di indice di avvio nell'intervallo corrisponde a un indice pari a 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.

Eseguire il rendering di polilinee sensibili al traffico con l'SDK di Maps

Consigliamo di mostrare le polilinee attente al traffico sulla mappa utilizzando le varie funzionalità offerte dagli SDK di Google Maps, tra cui colori, tratti e pattern personalizzati lungo i tratti di polilinea. Per maggiori dettagli sull'utilizzo delle polilinee, vedi Funzionalità Polyline per Android e Funzionalità Polyline per iOS.

Esempio di rendering di Polyline

Gli utenti dell'SDK di Maps hanno la possibilità di definire una logica di mappatura personalizzata tra le categorie di velocità e gli schemi di rendering polilinea. Ad esempio, si potrebbe decidere di visualizzare la velocità "NORMALE" come una linea blu spessa sulla mappa, mentre la velocità "LENTO" potrebbe essere visualizzata come una linea arancione spessa e così via.

I seguenti snippet aggiungono una polilinea blu spessa con segmenti geodetici, da Boubourne a Perth. Per ulteriori informazioni, consulta la pagina Personalizzare l'aspetto (per Android) e Personalizzare Polyline (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