Routen-Polylinien anfordern

Die Polyliniencodierung ist ein verlustbehafteter Komprimierungsalgorithmus, mit dem Sie eine Reihe von Koordinaten, z. B. eine Route, als einzelnen String speichern können. Bei der Codierung wird ein Binärwert mithilfe des base64-Codierungsschemas in eine Reihe von Zeichencodes für ASCII-Zeichen umgewandelt. Eine vollständige Beschreibung des Codierungsprozesses finden Sie unter Algorithmusformat für codierte Polylinien.

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

  • Einfache Polylinie (Standardeinstellung); stellt eine Route dar, aber ohne in die Polylinie eingebettete Verkehrsinformationen. Anfragen, die eine einfache Polylinie zurückgeben, werden zum Routes Basic-Tarif abgerechnet. Weitere Informationen zur Abrechnung für die Routes API

  • Verkehrsabhängige Polylinie 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 verkehrsabhängige Polylinien werden zum Tarif „Routes Preferred“ 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:

  • Unter Qualität im Vergleich zu Latenz finden Sie Informationen zum Konfigurieren der Qualität der Polylinie.
  • Unter Algorithmusformat für codierte Polylinien wird der Algorithmus zur Codierung einer Polylinie beschrieben.

  • Mit dem interaktiven Codierungsprogramm für Polylinien können Sie codierte Polylinien auf einer Benutzeroberfläche erstellen oder Polylinien decodieren, die auf einer Karte angezeigt werden. Verwenden Sie dieses Dienstprogramm beispielsweise, um eine Polylinie zu decodieren, die mit dem folgenden Code erstellt wurde.

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

Polylinien werden durch ein Polyline-Objekt (REST) oder ein Polyline-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 Abschnittsebene wird in der Antwort für jeden Abschnitt der Route eine Polylinie zurückgegeben. Dazu wird routes.legs.polyline eingefügt.

  • Auf Schrittebene wird in der Antwort für jeden Schritt des Abschnitts eine Polylinie zurückgegeben. Dazu wird routes.legs.steps.polyline eingefügt.

So können Sie beispielsweise eine Polylinie für die gesamte Route, für jeden Abschnitt und für jeden Schritt jedes Abschnitts zurückgeben:

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 Streckenabschnitt. Daher sind die Polylinie für den Abschnitt und 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 Streckenabschnitte 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"
      }
    }
  ]
}

Codierungstyp für Polylinien konfigurieren

Verwenden Sie die Anfrageoption polylineEncoding, um den Polylinientyp zu steuern. Mit der Eigenschaft polylineEncoding wird angegeben, wie die Polylinie codiert wird: ENCODED_POLYLINE (Standardeinstellung), d. h. der Codierungsalgorithmus für Polylinien, oder GEO_JSON_LINESTRING, d. h. das GeoJSON-LineString-Format verwenden.

Hier ein 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'

Polylinie mit Verkehrserkennung 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.

Verkehrsfähige Polylinien 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 anfänglichen (inklusiven) und letzten (exklusiven) Polylinienpunkte definiert.

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

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

Wenn Sie eine Anfrage zur Berechnung einer Polylinie, die den Traffic berücksichtigt, 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. Bei Anfragen für andere Mobilitätsformen wird ein Fehler zurückgegeben.

  • 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 Antworteigenschaften zurückgegeben werden sollen:

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

    • Auf Abschnittsebene werden durch Angabe von routes.legs.travelAdvisory alle Reiseinformationen in der Antwort für jeden Abschnitt der Route zurückgegeben. Wenn nur 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 die Verkehrslage berücksichtigt wird

In der Antwort werden Verkehrsdaten in der Polylinie codiert und sind im Feld travelAdvisory vom Typ RouteLegTravelAdvisory (bei jedem Abschnitt) und RouteTravelAdvisory-Objekt (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 Geschwindigkeitsmessung für ein Routenintervall wie NORMAL, SLOW oder TRAFFIC_JAM. Das gesamte Objekt-Array 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 seine startPolylinePointIndex, endPolylinePointIndex und die entsprechende Geschwindigkeitskategorie beschrieben. Beachten Sie, dass das Fehlen des Startindex innerhalb des Intervalls gemäß den Proto3-Verfahren dem Index 0 entspricht.

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

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

In diesem Fall waren die Verkehrsbedingungen von Index 2 bis Index 4 identisch.

Polylinien mit Verkehrserkennung mit dem Maps SDK rendern

Wir empfehlen, verkehrsrelevante Polylinien auf der Karte mithilfe der verschiedenen Funktionen der Google Maps SDKs darzustellen, darunter benutzerdefinierte Farben, Striche und Muster entlang der Polylinien. Weitere Informationen zur Verwendung von Polylinien finden Sie unter Polylinienfunktionen für Android und Polylinienfunktionen für iOS.

Beispiel für das Rendern einer Polylinie

Die Nutzer des Maps SDK haben die Möglichkeit, eine benutzerdefinierte Zuordnungslogik zwischen den Geschwindigkeitskategorien und den Renderingschemas für Polylinien zu definieren. Ein Beispiel: Die Geschwindigkeit „Normal“ wird als dicke blaue Linie auf der Karte angezeigt, während die Geschwindigkeit „Langsam“ als dicke orangefarbene Linie dargestellt werden soll.

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