Routen-Polylinien anfordern

Entwickler im Europäischen Wirtschaftsraum (EWR)

Die Methode computeRoutes (REST) und die ComputeRoutes Methode (gRPC) geben die Route, die durch eine Polylinie dargestellt wird, als Teil der Antwort zurück. Diese APIs geben zwei Arten von Polylinien zurück:

  • Einfache Polylinie (Standard): stellt eine Route dar, enthält aber keine Verkehrsinformationen. Anfragen, die eine einfache Polylinie zurückgeben, werden zum Tarif „Routes Basic“ abgerechnet. Weitere Informationen zur Abrechnung der Routes API

  • Polylinie mit Verkehrsinformationen: enthält Informationen zur Verkehrslage auf der Route. Die Verkehrslage wird in Geschwindigkeitskategorien (NORMAL, SLOW, TRAFFIC_JAM) ausgedrückt, die für ein bestimmtes Intervall der Polylinie gelten. Anfragen für Polylinien mit Verkehrsinformationen werden zum Tarif „Routes Preferred“ abgerechnet. Weitere Informationen zur Abrechnung der Routes API Weitere Informationen finden Sie unter Polylinienqualität konfigurieren.

Weitere Informationen zu Polylinien:

Einfache Polylinie für eine Route, einen Abschnitt oder einen Schritt anfordern

Eine Polylinie wird durch ein Polyline-Objekt (REST) oder Polyline-Objekt (gRPC) dargestellt. Sie können eine Polylinie in der Antwort auf Routen-, Abschnitts- und Schrittebene zurückgeben.

Geben Sie mit der Feldmaske für die Antwort an, welche Polylinie zurückgegeben werden soll:

  • Auf Routenebene: Wenn Sie eine Polylinie in der Antwort zurückgeben möchten, fügen Sie routes.polyline in die Feldmaske für die Antwort ein.

  • Auf Abschnittsebene: Wenn Sie eine Polylinie in der Antwort für jeden Abschnitt der Route zurückgeben möchten, fügen Sie routes.legs.polyline ein.

  • Auf Schrittebene: Wenn Sie eine Polylinie in der Antwort für jeden Schritt von dem Abschnitt zurückgeben möchten, fügen Sie routes.legs.steps.polyline ein.

Beispiel: So geben Sie eine Polylinie für die gesamte Route, für jeden Abschnitt und für jeden Schritt jedes Abschnitts zurück:

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'

Diese Anfrage gibt die folgende Antwort zurück, die die Polylinie für die Route, für jeden Abschnitt der Route und für jeden Schritt des Abschnitts enthält:

{
  "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_@@_@?"
      }
    }
  ]
}

Da diese Anfrage nur einen Start- und einen Zielort enthält, enthält die zurückgegebene Route nur einen Abschnitt. Daher sind die Polylinien für den Abschnitt und für die Route identisch.

Wenn Sie der Anfrage einen Zwischenwegpunkt hinzufügen, enthält die zurückgegebene Route zwei Abschnitte:

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'

Diese Anfrage gibt zwei Abschnitte mit jeweils einer eindeutigen Polylinie und eine Polylinie für die gesamte Route zurück:

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

Polylinienqualität

Die Qualität einer Polylinie kann mit den folgenden Begriffen beschrieben werden:

  • Die Gleitkommapräzision der Punkte

    Punkte werden als Breiten- und Längengradwerte angegeben, die im Gleitkommaformat mit einfacher Genauigkeit dargestellt werden. Das funktioniert gut für kleine Werte (die genau dargestellt werden können), aber die Präzision nimmt mit zunehmenden Werten aufgrund von Rundungsfehlern bei Gleitkommazahlen ab.

    In computeRoutes Methode (REST) und ComputeRoutes, wird dies durch polylineEncoding gesteuert.

  • Die Anzahl der Punkte, aus denen die Polylinie besteht

    Je mehr Punkte vorhanden sind, desto glatter ist die Polylinie (insbesondere in Kurven).

    In computeRoutes method (REST) and ComputeRoutes, dies wird durch polylineQuality gesteuert.

Codierungstyp für Polylinien konfigurieren

Verwenden Sie die Anfrageoption polylineEncoding, um den Polylinientyp zu steuern. Mit der polylineEncoding Eigenschaft wird festgelegt, ob die Polylinie als ENCODED_POLYLINE (Standard) codiert wird, d. h. das Algorithmusformat für codierte Polylinien wird verwendet, oder als GEO_JSON_LINESTRING, d. h. das GeoJSON-Format für LineStrings wird verwendet.

Beispiel für den Anfragetext:

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'

Polylinienqualität konfigurieren

polylineQuality gibt die Qualität der Polylinie als HIGH_QUALITY oder OVERVIEW (Standard) an. Bei OVERVIEW wird die Polylinie mit einer kleinen Anzahl von Punkten erstellt und hat eine geringere Anfragelatenz als HIGH_QUALITY.

Beispiel für den Anfragetext:

{
  "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",
  ...
}

Polylinie mit Verkehrsinformationen anfordern

Die oben gezeigten Beispiele geben alle einfache Polylinien zurück, d. h. Polylinien ohne Verkehrsinformationen. Sie können auch anfordern, dass die Polylinie Verkehrsinformationen für die Route und für jeden Abschnitt der Route enthält.

Polylinien mit Verkehrsinformationen enthalten Informationen zur Verkehrslage auf der Route. Die Verkehrslage wird in Geschwindigkeitskategorien (NORMAL, SLOW, TRAFFIC_JAM) für ein bestimmtes Intervall der Antwortpolylinie ausgedrückt. Die Intervalle werden durch die Indizes ihrer Start- (einschließlich) und Endpunkte (ausschließlich) der Polylinie definiert.

Die folgende Antwort zeigt beispielsweise NORMAL-Traffic zwischen den Polylinienpunkten 2 und 4:

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

Wenn Sie eine Anfrage senden möchten, um eine Polylinie mit Verkehrsinformationen zu berechnen, legen Sie die folgenden Eigenschaften in der Anfrage fest:

  • Setzen Sie das Arrayfeld extraComputations auf TRAFFIC_ON_POLYLINE, um die Trafficberechnung zu aktivieren.

  • Setzen Sie travelMode auf DRIVE oder TWO_WHEELER. Bei Anfragen für andere Verkehrsmittel wird ein Fehler zurückgegeben.

  • Geben Sie in der Anfrage entweder die TRAFFIC_AWARE oder TRAFFIC_AWARE_OPTIMAL Routing präferenz an. Weitere Informationen finden Sie unter Qualität im Vergleich zur Latenz konfigurieren.

  • Legen Sie eine Feldmaske für die Antwort fest, die angibt, dass die Antwortattribute zurückgegeben werden sollen:

    • Auf Routenebene: Wenn Sie alle Reiseinformationen in der Antwort zurückgeben möchten, fügen Sie routes.travelAdvisory in die Feldmaske für die Antwort ein. Wenn Sie nur die Verkehrsinformationen zurückgeben möchten, geben Sie routes.travelAdvisory.speedReadingIntervals an.

    • Auf Abschnittsebene: Wenn Sie alle Reiseinformationen in der Antwort für jeden Abschnitt der Route zurückgeben möchten, fügen Sie routes.legs.travelAdvisory ein. Wenn Sie nur die Verkehrsinformationen zurückgeben möchten, geben Sie routes.legs.travelAdvisory.speedReadingIntervals an.

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'

Beispielantwort für eine Polylinie mit Verkehrsinformationen

In der Antwort werden die Verkehrsdaten in der Polylinie codiert und sind im travelAdvisory Feld enthalten, das vom Typ RouteLegTravelAdvisory -Objekt (jeder Abschnitt) und RouteTravelAdvisory-Objekt (Route) ist.

Beispiel:

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

Sowohl RouteTravelAdvisory als auch RouteLegTravelAdvisory enthalten ein Arrayfeld namens speedReadingIntervals mit Informationen zur Verkehrsgeschwindigkeit. Jedes Objekt im Array wird durch ein SpeedReadingInterval-Objekt (REST) oder SpeedReadingInterval-Objekt (gRPC) dargestellt.

Ein SpeedReadingInterval-Objekt enthält die Geschwindigkeitsangabe für ein Routenintervall, z. B. NORMAL, SLOW oder TRAFFIC_JAM. Das gesamte Array von Objekten deckt die gesamte Polylinie der Route ohne Überlappung ab. Der Startpunkt eines angegebenen Intervalls ist derselbe wie der Endpunkt des vorherigen Intervalls.

Jedes Intervall wird durch startPolylinePointIndex, endPolylinePointIndex und die entsprechende Geschwindigkeitskategorie beschrieben. Beachten Sie, dass das Fehlen eines Startindex im Intervall gemäß den proto3-Praktiken dem Index 0 entspricht in Übereinstimmung mit den proto3 Praktiken.

Die Werte startPolylinePointIndex und endPolylinePointIndex sind nicht immer aufeinanderfolgend. Beispiel:

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

In diesem Fall war die Verkehrslage von Index 2 bis Index 4 gleich.

Polylinien mit Verkehrsinformationen mit dem Maps SDK rendern

Wir empfehlen, Polylinien mit Verkehrsinformationen auf der Karte mit den verschiedenen Funktionen der Google Maps SDKs anzuzeigen, einschließlich benutzerdefinierter Farben, Striche und Muster entlang der Polylinienabschnitte. Weitere Informationen zur Verwendung von Polylinien, siehe Polylinienfunktionen für Android und Polylinien funktionen für iOS.

Beispiel für das Rendern von Polylinien

Die Nutzer des Maps SDK haben die Möglichkeit, eine benutzerdefinierte Zuordnungslogik zwischen den Geschwindigkeitskategorien und den Schemas für das Rendern von Polylinien zu definieren. Beispielsweise kann die Geschwindigkeit „NORMAL“ als dicke blaue Linie auf der Karte angezeigt werden, während die Geschwindigkeit „SLOW“ beispielsweise als dicke orangefarbene Linie angezeigt wird.

Mit den folgenden Snippets wird eine dicke blaue Polylinie mit geodätischen Segmenten von Melbourne nach Perth hinzugefügt. Weitere Informationen finden Sie unter Erscheinungsbild anpassen (für Android) und Polylinie anpassen (für 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

Codierte Polylinien mit „Suche entlang der Route“ verwenden

Verwenden Sie die Places API-Textsuche, um entlang einer berechneten Route zu suchen. Sie übergeben die codierte Polylinie einer vorab berechneten Route aus der Routes API-Methode „Compute Routes“ an die Text Search-Anfrage. Die Antwort enthält dann Orte, die den Suchkriterien entsprechen und sich in der Nähe der angegebenen Route befinden. Weitere Informationen finden Sie unter Suche entlang einer Route.

Beispiel: So geben Sie Cafés entlang der Route zwischen Start- und Zielort zurück:

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();