Richiedi polilinee percorso

Sviluppatori dello Spazio economico europeo (SEE)

Il metodo computeRoutes (REST) e il metodo ComputeRoutes (gRPC) restituiscono entrambi l'itinerario rappresentato da una polilinea come parte della risposta. Queste API restituiscono due tipi di polilinee:

  • Polilinea di base (impostazione predefinita), rappresenta un percorso ma senza informazioni sul traffico incorporate nella polilinea. Le richieste che restituiscono una polilinea di base vengono fatturate alla tariffa Routes Basic. Scopri di più sulla fatturazione per l'API Routes.

  • Polilinea in base 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) applicabili a un determinato intervallo della polilinea. Le richieste di polilinee sensibili al traffico vengono fatturate alla tariffa Routes Preferred. 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:

Richiedere una polilinea di base per un percorso, 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 percorso, itinerario e passaggio.

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 segmento, restituisci una polilinea nella risposta per ogni segmento dell'itinerario includendo routes.legs.polyline.

  • A livello di passaggio, restituisci una polilinea nella risposta per ogni passaggio della tratta includendo routes.legs.steps.polyline.

Ad esempio, per restituire una polilinea per l'intero percorso, 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 l'itinerario, per ogni tratto dell'itinerario 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, l'itinerario restituito contiene una sola tratta. Pertanto, la polilinea per la tratta e per il percorso sono le stesse.

Se aggiungi un waypoint intermedio alla richiesta, l'itinerario restituito contiene due tappe:

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'intero itinerario:

{
  "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, rappresentati in formato in virgola mobile a precisione singola. Funziona bene per valori piccoli (che possono essere rappresentati con precisione), ma la precisione diminuisce man mano che i valori aumentano a causa di errori di arrotondamento in virgola mobile.

    Nei metodi computeRoutes (REST) e ComputeRoutes, questo è controllato da polylineEncoding.

  • Il numero di punti che compongono la polilinea

    Più punti ci sono, più la polilinea è uniforme (soprattutto nelle curve).

    Nei metodi computeRoutes (REST) e ComputeRoutes, questo è 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 la polilinea verrà codificata come ENCODED_POLYLINE (impostazione predefinita), il che significa che verrà utilizzato il formato dell'algoritmo di codifica delle polilinee, oppure 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 (valore predefinito). Con OVERVIEW, la polilinea è composta da un numero ridotto di punti e ha una latenza della 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 in base al 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 l'itinerario e per ogni tratta dell'itinerario.

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 della risposta. Gli intervalli sono definiti dagli indici dei punti della polilinea iniziale (inclusi) e finale (esclusi).

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

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

Per inviare una richiesta per calcolare una polilinea in base al 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 per qualsiasi altra modalità di viaggio restituiscono un errore.

  • Specifica la preferenza di routing TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL nella 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 itinerario, 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 dell'itinerario 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 in base al traffico

Nella risposta, i dati sul traffico sono codificati nella polilinea e sono contenuti nel campo travelAdvisory, di tipo oggetto RouteLegTravelAdvisory (ogni tratta) e oggetto RouteTravelAdvisory (itinerario).

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 denominato speedReadingIntervals che contiene informazioni sulla velocità del traffico. Ogni oggetto dell'array è rappresentato da un oggetto SpeedReadingInterval (REST) o SpeedReadingInterval (gRPC).

Un oggetto SpeedReadingInterval include la lettura della velocità per un intervallo di percorso, ad esempio NORMAL, SLOW o TRAFFIC_JAM. L'intero array di oggetti copre l'intera polilinea del percorso senza sovrapposizioni. Il punto iniziale di un intervallo specificato è uguale al punto finale dell'intervallo precedente.

Ogni intervallo è descritto dal relativo 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 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.

Esegui il rendering di polilinee in base al traffico con Maps SDK

Ti consigliamo di visualizzare le polilinee con informazioni sul traffico sulla mappa utilizzando le varie funzionalità offerte dagli SDK Google Maps, tra cui colori, tratti e pattern personalizzati lungo i tratti della polilinea. Per ulteriori 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, 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 arancione spessa.

I seguenti snippet aggiungono una polilinea blu spessa con segmenti geodetici da Melbourne a Perth. Per maggiori informazioni, vedi Personalizzazione degli aspetti (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 polilinee codificate con Cerca lungo il percorso

Utilizza la ricerca di testo dell'API Places per cercare lungo un percorso calcolato. Passi la polilinea codificata di un percorso precalcolato dall'API Routes Compute Routes alla richiesta di ricerca di testo. La risposta contiene quindi i luoghi che corrispondono ai criteri di ricerca e si trovano anche vicino al percorso specificato. Per maggiori dettagli, vedi Ricerca lungo un percorso.

Ad esempio, per visualizzare i bar lungo il percorso 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();