Routen-Polylinien anfordern

Entwickler im Europäischen Wirtschaftsraum (EWR)

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

  • Einfache Polylinie (Standard): Stellt eine Route dar, aber ohne Verkehrsinformationen, die in die Polylinie eingebettet sind. Anfragen, die eine einfache Polylinie zurückgeben, werden zum Routes Basic-Tarif abgerechnet. Weitere Informationen zur Abrechnung für die Routes API

  • Polylinien mit Berücksichtigung der aktuellen Verkehrslage enthalten 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 verkehrsabhängige Polylinien werden zum bevorzugten Preis für die Routes API abgerechnet. Weitere Informationen zur Abrechnung für die Routes API Weitere Informationen finden Sie unter Polylinienqualität konfigurieren.

Weitere Informationen zu Polylinien finden Sie unter:

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

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

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

  • Auf Routenebene können Sie eine Polylinie in der Antwort zurückgeben, indem Sie routes.polyline in die Antwortfeldmaske aufnehmen.

  • Auf Ebene des Teilstücks: Geben Sie in der Antwort für jedes Teilstück der Route eine Polylinie zurück, indem Sie routes.legs.polyline einfügen.

  • Auf Schrittebene wird in der Antwort für jeden Schritt des Legs eine Polylinie zurückgegeben, wenn Sie routes.legs.steps.polyline einfügen.

Um beispielsweise eine Polylinie für die gesamte Route, für jeden Abschnitt und für jeden Schritt jedes Abschnitts zurückzugeben:

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 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 zurück, die jeweils eine eindeutige Polylinie haben, sowie eine Polylinie für die gesamte Route:

{
  "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 Gleitkommazahl-Genauigkeit 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. Die Genauigkeit nimmt jedoch mit zunehmenden Werten aufgrund von Rundungsfehlern bei Gleitkommazahlen ab.

    In der Methode computeRoutes (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 der Methode computeRoutes (REST) und ComputeRoutes wird dies durch polylineQuality gesteuert.

Typ der Polylinien-Codierung konfigurieren

Verwenden Sie die Anfrageoption polylineEncoding, um den Polylinien-Typ zu steuern. Mit der Eigenschaft polylineEncoding wird festgelegt, ob die Polylinie als ENCODED_POLYLINE (Standard) codiert wird. In diesem Fall wird das Format des Algorithmus für codierte Polylinien verwendet. Andernfalls wird sie als GEO_JSON_LINESTRING codiert. In diesem Fall wird das GeoJSON-LineString-Format 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 (Standardeinstellung) an. Bei OVERVIEW wird die Polylinie aus einer kleinen Anzahl von Punkten zusammengesetzt und die Anfrage hat eine geringere Latenz als bei 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",
  ...
}

Verkehrsabhängige Polylinie anfordern

Bei den oben gezeigten Beispielen werden alle grundlegenden Polylinien zurückgegeben, d. h. Polylinien ohne Verkehrsinformationen. Außerdem können Sie anfordern, dass die Polylinie Verkehrsinformationen für die Route und für jeden Abschnitt der Route enthält.

Verkehrsabhängige Polylinien enthalten Informationen zur Verkehrslage entlang der Route. Die Verkehrsbedingungen werden für ein bestimmtes Intervall der Antwort-Polylinie in Geschwindigkeitskategorien (NORMAL, SLOW, TRAFFIC_JAM) ausgedrückt. Die Intervalle werden durch die Indexe 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 zum Berechnen einer verkehrsabhängigen Polylinie stellen möchten, legen Sie die folgenden Eigenschaften in der Anfrage fest:

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

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

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

  • Legen Sie eine Antwortfeldmaske fest, mit der die zurückzugebenden Antwortattribute angegeben werden:

    • Auf Routenebene werden alle Reiseinformationen in der Antwort zurückgegeben, wenn Sie routes.travelAdvisory in die Feldmaske für die Antwort aufnehmen. Wenn Sie nur die Traffic-Informationen zurückgeben möchten, geben Sie routes.travelAdvisory.speedReadingIntervals an.

    • Auf Abschnittsebene: Geben Sie alle Reiseinformationen in der Antwort für jeden Abschnitt der Route zurück, indem Sie routes.legs.travelAdvisory einfügen. 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 verkehrsabhängige Polylinie

In der Antwort werden Verkehrsdaten in der Polylinie codiert und sind im Feld travelAdvisory 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, das Informationen zur Verkehrsgeschwindigkeit enthält. Jedes Objekt im Array wird durch ein SpeedReadingInterval-Objekt (REST) oder ein SpeedReadingInterval-Objekt (gRPC) dargestellt.

Ein SpeedReadingInterval-Objekt enthält Informationen zur Geschwindigkeit für ein Routenintervall, z. B. NORMAL, SLOW oder TRAFFIC_JAM. Das gesamte Array von Objekten deckt die gesamte Polylinie der Route ohne Überschneidung 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 innerhalb des Intervalls dem Index 0 gemäß den proto3-Praktiken entspricht.

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

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

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

Verkehrsabhängige Polylinien mit dem Maps SDK rendern

Wir empfehlen, Polylinien mit Verkehrsdaten auf der Karte mithilfe der verschiedenen Funktionen der Google Maps SDKs darzustellen, z. B. mit benutzerdefinierten Farben, Strichen und Mustern entlang der Polylinienabschnitte. Weitere Informationen zur Verwendung von Polylinien finden Sie unter Polylinienfunktionen für Android und Polylinienfunktionen 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 könnte die Geschwindigkeit „NORMAL“ als dicke blaue Linie auf der Karte dargestellt werden, während die Geschwindigkeit „LANGSAM“ 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 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

Codierte Polylinien mit „Suche entlang der Route“ verwenden

Mit der Places API Text Search können Sie entlang einer berechneten Route suchen. Sie übergeben die codierte Polylinie einer vorab berechneten Route aus der Routes API 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.

Wenn Sie beispielsweise Cafés entlang der Route zwischen Start- und Zielort zurückgeben möchten, geben Sie Folgendes ein:

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