Routen-Polylinien anfordern

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

  • Einfache Polylinie (Standardeinstellung) Anfragen, die eine einfache Polylinie zurückgeben, werden zum Routes Basic-Preis abgerechnet. Weitere Informationen zur Abrechnung für die Routes API

  • Polylinie mit Verkehrserkennung, enthält Informationen zur Verkehrslage entlang der Route. Die Verkehrslage wird in Form von Geschwindigkeitskategorien (NORMAL, SLOW, TRAFFIC_JAM) für ein bestimmtes Intervall der Polylinie ausgedrückt. Anfragen für Polylinien mit Verkehrsdaten werden zum Tarif für bevorzugte Routen abgerechnet. Weitere Informationen zur Abrechnung für die Routes API Weitere Informationen finden Sie unter Qualität von Polylinien konfigurieren.

Weitere Informationen zu Polylinien finden Sie unter:

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

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

Geben Sie mithilfe der Antwortfeldmaske an, welche Polylinie zurückgegeben werden soll:

  • Auf Routenebene wird in der Antwort eine Polylinie zurückgegeben, indem routes.polyline in die Antwortfeldmaske aufgenommen wird.

  • Auf Streckenabschnitt: Geben Sie in der Antwort für jeden Abschnitt der Route eine Polylinie zurück, indem Sie routes.legs.polyline einbeziehen.

  • Auf Schrittebene wird in der Antwort für jeden Schritt des Abschnitts eine Polylinie zurückgegeben, indem routes.legs.steps.polyline aufgenommen wird.

So geben Sie beispielsweise eine Polylinie für die gesamte Route, für jeden Abschnitt und für jeden Schritt jedes Abschnitts 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"
}' \
-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 einzelnen Abschnitt. Daher sind die Polylinie für den Streckenabschnitt und für die Route identisch.

Wenn Sie der Anfrage einen Wegpunkt 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 so beschrieben werden:

  • Die Gleitkommagenauigkeit der Punkte

    Punkte werden als Breiten- und Längengradwerte angegeben, die im Gleitkommaformat mit einfacher Genauigkeit dargestellt werden. Das funktioniert gut bei kleinen Werten, die genau dargestellt werden können. Die Genauigkeit nimmt jedoch aufgrund von Rundungsfehlern mit Gleitkommazahlen ab, wenn die Werte zunehmen.

    In der Methode computeRoutes (REST) und ComputeRoutes wird dies von polylineEncoding gesteuert.

  • Die Anzahl der Punkte, aus denen die Polylinie besteht

    Je mehr Punkte vorhanden sind, desto gleichmäßiger ist die Polylinie (insbesondere bei Kurven).

    In der Methode computeRoutes (REST) und ComputeRoutes wird dies von polylineQuality gesteuert.

Codierungstyp für Polylinie konfigurieren

Verwenden Sie die Anfrageoption polylineEncoding, um den Polylinientyp zu steuern. Mit der Eigenschaft polylineEncoding wird festgelegt, ob die Polylinie als ENCODED_POLYLINE (Standardeinstellung) codiert wird. Das bedeutet, dass das Format des Algorithmus für codierte Polylinien verwendet wird, oder als GEO_JSON_LINESTRING, d. h. das GeoJSON-LineString-Format.

Zum Beispiel in 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'

Poyline-Qualität konfigurieren

polylineQuality gibt die Qualität der Polylinie als HIGH_QUALITY oder OVERVIEW (Standardeinstellung) an. Mit OVERVIEW besteht die Polylinie aus einer kleinen Anzahl von Punkten und hat eine niedrigere Anfragelatenz als HIGH_QUALITY.

Zum Beispiel in 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 Daten zur Verkehrslage anfordern

In den obigen Beispielen werden grundlegende Polylinien zurückgegeben, d. h. Polylinien ohne Verkehrsinformationen. Darüber hinaus können Sie auch angeben, dass die Polylinie Verkehrsinformationen für die Route und für jeden Abschnitt der Route enthalten soll.

Polylinien mit Verkehrserkennung enthalten Informationen zur Verkehrslage entlang der Route. Die Verkehrslage wird in Form von Geschwindigkeitskategorien (NORMAL, SLOW, TRAFFIC_JAM) für ein bestimmtes Intervall der Antwortpolygone ausgedrückt. Die Intervalle werden durch die Indexe ihrer Start- (inklusiven) und letzten (exklusiven) Polylinienpunkte definiert.

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

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

Wenn Sie eine Anfrage zur Berechnung einer verkehrsabhängigen Polylinie stellen möchten, legen Sie die folgenden Attribute in der Anfrage fest:

  • Legen Sie das Arrayfeld extraComputations auf TRAFFIC_ON_POLYLINE fest, um die Traffic-Berechnung zu aktivieren.

  • Legen Sie travelMode auf DRIVE oder TWO_WHEELER fest. Anfragen für eine andere Mobilitätsform geben einen Fehler zurück.

  • Geben Sie in der Anfrage entweder die Routingeinstellung TRAFFIC_AWARE oder TRAFFIC_AWARE_OPTIMAL an. Weitere Informationen finden Sie unter Qualität und Latenz konfigurieren.

  • Legen Sie eine Antwortfeldmaske fest, die angibt, dass die Antwortattribute zurückgegeben werden sollen:

    • Auf Routenebene werden alle Fahrtinformationen in der Antwort zurückgegeben, indem routes.travelAdvisory in die Antwortfeldmaske aufgenommen wird. Wenn nur die Verkehrsinformationen zurückgegeben werden sollen, geben Sie routes.travelAdvisory.speedReadingIntervals an.

    • Auf Streckenabschnitt: Geben Sie durch Angabe von routes.legs.travelAdvisory alle Reiseinformationen in der Antwort für jeden Abschnitt der Route zurück. Wenn nur die Verkehrsinformationen zurückgegeben werden sollen, 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, bei der der Verkehr berücksichtigt wird

In der Antwort sind Verkehrsdaten in der Polylinie codiert und im Feld travelAdvisory vom Typ RouteLegTravelAdvisory (jede Etappe) und des Objekts RouteTravelAdvisory (Route) enthalten.

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 mit dem Namen speedReadingIntervals, das Informationen zur Verkehrsgeschwindigkeit enthält. Jedes Objekt im Array wird durch ein Objekt vom Typ SpeedReadingInterval (REST) oder SpeedReadingInterval (gRPC) dargestellt.

Ein SpeedReadingInterval-Objekt enthält Geschwindigkeitsmessungen für ein Routenintervall wie NORMAL, SLOW oder TRAFFIC_JAM. Das gesamte Objektarray deckt die gesamte Polylinie der Route ohne Überschneidung ab. Der Startpunkt eines angegebenen Intervalls ist mit dem Endpunkt des vorherigen Intervalls identisch.

Jedes Intervall wird durch startPolylinePointIndex, endPolylinePointIndex und die entsprechende Geschwindigkeitskategorie beschrieben. Beachten Sie, dass der fehlende Startindex innerhalb des Intervalls Index 0 gemäß den Proto3-Praktiken entspricht.

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 identisch.

Polylinien mit Verkehrsdaten mit dem Maps SDK rendern

Wir empfehlen, Polylinien, die den Straßenverkehr berücksichtigen, mithilfe der verschiedenen Funktionen der Google Maps SDKs auf der Karte darzustellen, z. B. benutzerdefinierte Farben, Striche und Muster entlang der Polylinien. Weitere Informationen zur Verwendung von Polylinien finden Sie unter Polylinien-Elemente für Android und Polylinien-Elemente für iOS.

Beispiel für Polylinien-Rendering

Die Nutzer des Maps SDK haben die Möglichkeit, eine benutzerdefinierte Zuordnungslogik zwischen den Geschwindigkeitskategorien und den Renderingschemas der Polylinie zu definieren. Sie können z. B. die Geschwindigkeit „Normal“ als dicke blaue Linie auf der Karte darstellen, während die Geschwindigkeit bei „Langsam“ als orangefarbene Linie dargestellt 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 Darstellung 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