„Directions“-Dienst

Übersicht

Mit dem DirectionsService-Objekt lassen sich Routen für verschiedene Verkehrsmittel berechnen. Das Objekt kommuniziert mit dem „Directions“-Dienst der Google Maps API. Dieser nimmt entsprechende Anfragen entgegen und gibt eine effiziente Route zurück. Die Route wird primär nach der Fahrzeit optimiert, es können aber auch andere Faktoren berücksichtigt werden, wie z. B. die Entfernung oder die Anzahl der Abzweige. Sie können die Routenergebnisse entweder selbst verarbeiten oder das DirectionsRenderer-Objekt verwenden, um sie zu rendern.

Um den Start- oder Zielort in einer Routenanfrage anzugeben, können Sie einen Abfragestring wie „Chicago, IL“ oder „Darwin, NSW, Australien“, einen LatLng-Wert oder ein Place-Objekt verwenden.

Der „Directions“-Dienst kann mehrteilige Wegbeschreibungen mit einer Reihe von Wegpunkten zurückgeben. Routen werden als Polylinie auf der Karte oder zusätzlich als Textbeschreibung in einem <div>-Element (z. B. „Nach rechts auf Talstraße abbiegen“) angezeigt.

Erste Schritte

Bevor Sie den „Directions“-Dienst in der Maps JavaScript API verwenden, müssen Sie die Directions API in der Google Cloud Console in dem Projekt aktivieren, das Sie für die Maps JavaScript API eingerichtet haben.

So rufen Sie die Liste der aktivierten APIs auf:

  1. Rufen Sie die Google Cloud Console auf.
  2. Klicken Sie auf die Schaltfläche Projekt auswählen, wählen Sie das Projekt aus, das Sie für die Maps JavaScript API eingerichtet haben, und klicken Sie auf Öffnen.
  3. Suchen Sie im Dashboard in der Liste der APIs nach Directions API.
  4. Wenn die API in der Liste angezeigt wird, müssen Sie nichts weiter tun. Ist die API nicht aufgeführt, aktivieren Sie sie:
    1. Wählen Sie oben auf der Seite API AKTIVIEREN aus, um den Tab Bibliothek aufzurufen. Alternativ können Sie im Menü auf der linken Seite Bibliothek auswählen.
    2. Suchen Sie nach der Directions API und wählen Sie sie aus der Ergebnisliste aus.
    3. Wählen Sie AKTIVIEREN aus. Wenn der Vorgang abgeschlossen ist, wird die Directions API auf dem Dashboard in der Liste der APIs angezeigt.

Preise und Richtlinien

Preise

Seit 16. Juli 2018 gilt für Maps, Routes und Places ein neues nutzungsorientiertes Preismodell (Pay as you go). Weitere Informationen zu den aktuellen Preisen und Nutzungslimits für die Verwendung des JavaScript-„Directions“-Diensts finden Sie unter Nutzung und Abrechnung für die Directions API.

Richtlinien

Die Nutzung des „Directions“-Diensts unterliegt den Richtlinien für die Directions API.

Routenanfragen

Der Zugriff auf den „Directions“-Dienst erfolgt asynchron, da die Google Maps API dazu einen externen Server aufrufen muss. Daher muss eine Callback-Methode übergeben werden, die nach Abschluss der Anfrage ausgeführt wird. Das Ergebnis wird dann über die Callback-Methode verarbeitet. Der „Directions“-Dienst gibt unter Umständen mehrere mögliche Wegbeschreibungen als Array separater routes[] zurück.

Wenn Sie den Dienst in der Maps JavaScript API verwenden möchten, erstellen Sie ein Objekt vom Typ DirectionsService und rufen Sie DirectionsService.route() auf, um eine Anfrage an den „Directions“-Dienst zu senden und dabei ein DirectionsRequest-Objektliteral zu übergeben, das die Eingabebedingungen und eine Callback-Methode enthält, die nach Erhalt der Antwort ausgeführt werden soll.

Das DirectionsRequest-Objektliteral enthält die folgenden Felder:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Erläuterungen zu den Feldern:

  • origin (erforderlich) gibt den Startort für die Berechnung der Route an. Dieser Wert kann als String (z. B. „Chicago, IL“), LatLng-Wert oder Place-Objekt angegeben werden. Wenn Sie ein Place-Objekt verwenden, können Sie eine Orts-ID, einen Abfragestring oder einen LatLng-Wert angeben. Sie können Orts-IDs aus den „Geocoding“-, „Place Search“- und „Place Autocomplete“-Diensten der Maps JavaScript API abrufen. Ein Beispiel für die Verwendung von Orts-IDs aus dem „Place Autocomplete“-Dienst finden Sie hier.
  • destination (erforderlich) gibt den Zielort für die Berechnung der Route an. Die Optionen entsprechen denen des origin-Felds.
  • travelMode (erforderlich) gibt an, welche Mobilitätsform der Berechnung der Route zugrunde gelegt werden soll. Die gültigen Werte sind im Abschnitt Mobilitätsformen unten beschrieben.
  • transitOptions (optional) gibt Werte an, die nur für Anfragen mit TRANSIT als travelMode gelten. Die gültigen Werte werden im Abschnitt Optionen für öffentliche Verkehrsmittel unten beschrieben.
  • drivingOptions (optional) gibt Werte an, die nur für Anfragen mit DRIVING als travelMode gelten. Die gültigen Werte werden im Abschnitt Optionen für Kraftfahrzeuge unten beschrieben.

  • unitSystem (optional) gibt an, welches Einheitensystem für die Anzeige der Ergebnisse verwendet werden soll. Die gültigen Werte werden im Abschnitt Einheitensysteme unten beschrieben.

  • waypoints[] (optional) gibt ein Array aus Wegpunkten (DirectionsWaypoint) an. Werden Wegpunkte angegeben, wird die Route so geändert, dass sie über die entsprechenden Orte führt. Wegpunkte werden als Objektliteral mit folgenden Feldern angegeben:

    • location gibt den Standort des Wegpunkts als LatLng-Wert, Place-Objekt oder String an, der geocodiert wird.
    • stopover ist ein boolescher Wert, der angibt, dass der Wegpunkt ein Zwischenhalt ist. Die Route wird dann entsprechend unterteilt.

    Weitere Informationen zu Wegpunkten finden Sie im Abschnitt Wegpunkte in Routen verwenden unten.

  • optimizeWaypoints (optional) gibt an, dass die Route mit den angegebenen waypoints optimiert werden kann, indem die Wegpunkte in eine effizientere Reihenfolge gebracht werden. Wenn true festgelegt ist, gibt der „Directions“-Dienst die neu angeordneten waypoints im Feld waypoint_order zurück. Weitere Informationen finden Sie unter Wegpunkte in Routen verwenden unten.
  • Ist provideRouteAlternatives (optional) auf true gesetzt, kann der „Directions“-Dienst mehrere alternative Routen in der Antwort zurückgeben. Durch alternative Routen kann sich die Antwortzeit des Servers jedoch verlängern. Diese Option ist nur für Anfragen ohne Wegpunkte verfügbar.
  • Ist avoidFerries (optional) auf true gesetzt, sollen bei der Berechnung der Route(n) Fähren möglichst vermieden werden.
  • Ist avoidHighways (optional) auf true gesetzt, sollen bei der Berechnung der Route(n) Autobahnen möglichst vermieden werden.
  • Ist avoidTolls (optional) auf true gesetzt, sollen bei der Berechnung der Route(n) Mautstraßen möglichst vermieden werden.
  • region (optional) gibt den Regionscode als Ländercode der Top-Level-Domain (ccTLD) an. Weitere Informationen finden Sie unten unter Gewichtung nach Region.

Unten sehen Sie ein DirectionsRequest-Beispiel:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Mobilitätsformen

Damit eine Route berechnet werden kann, müssen Sie die Mobilitätsform angeben, die verwendet werden soll. Folgende Mobilitätsformen werden derzeit unterstützt:

  • Bei DRIVING (Standardeinstellung) wird eine standardmäßige Wegbeschreibung auf Grundlage des Straßennetzes angefordert.
  • Bei BICYCLING werden Fahrradrouten mit Radwegen und bevorzugten Straßen angefordert.
  • Bei TRANSIT werden Routen mit öffentlichen Verkehrsmitteln angefordert.
  • Bei WALKING werden Fußgängerrouten auf Fußgängerwegen und Bürgersteigen angefordert.

In den Details zur Google Maps Platform-Abdeckung können Sie nachlesen, inwiefern Routen in den einzelnen Ländern unterstützt werden. Wenn Sie eine Route für eine Region anfordern, in der der entsprechende Routentyp nicht verfügbar ist, wird die Antwort DirectionsStatus="ZERO_RESULTS" zurückgegeben.

Hinweis: Fußgängerrouten enthalten unter Umständen keine ausgewiesenen Fußgängerwege. In diesen Fällen werden Warnungen im DirectionsResult zurückgegeben. Diese Warnungen müssen immer für den Nutzer eingeblendet werden. Wenn Sie nicht den standardmäßigen DirectionsRenderer verwenden, müssen Sie selbst dafür sorgen, dass sie angezeigt werden.

Optionen für öffentliche Verkehrsmittel

Die verfügbaren Optionen für „Directions“-Anfragen richten sich nach der Mobilitätsform. Bei Anfragen für öffentliche Verkehrsmittel werden die Optionen avoidHighways, avoidTolls, waypoints[] und optimizeWaypoints ignoriert. Sie können Routenoptionen für öffentliche Verkehrsmittel über das TransitOptions-Objektliteral angeben.

Routenanfragen für öffentliche Verkehrsmittel sind zeitsensitiv. Berechnungen werden nur für Zeiten in der Zukunft zurückgegeben.

Das TransitOptions-Objektliteral enthält die folgenden Felder:

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

Erläuterungen zu den Feldern:

  • arrivalTime (optional) gibt die gewünschte Ankunftszeit als Date-Objekt an. Ist die Ankunftszeit angegeben, wird die Abreisezeit ignoriert.
  • departureTime (optional) gibt die gewünschte Startzeit als Date-Objekt an. departureTime wird ignoriert, wenn arrivalTime angegeben ist. Wird kein Wert für departureTime oder arrivalTime angegeben, wird standardmäßig die aktuelle Uhrzeit verwendet.
  • modes[] (optional) ist ein Array aus einem oder mehreren TransitMode-Objektliteralen. Dieses Feld kann nur angegeben werden, wenn die Anfrage einen API-Schlüssel enthält. Jedes TransitMode-Objektliteral gibt ein bevorzugtes Verkehrsmittel an. Folgende Werte sind zulässig:
    • BUS gibt an, dass für die berechnete Route Busse bevorzugt werden sollen.
    • RAIL gibt an, dass für die berechnete Route Züge, Straßenbahnen, Stadtbahnen und U-Bahnen bevorzugt werden sollen.
    • SUBWAY gibt an, dass für die berechnete Route U-Bahnen bevorzugt werden sollen.
    • TRAIN gibt an, dass für die berechnete Route Züge bevorzugt werden sollen.
    • TRAM gibt an, dass für die berechnete Route Straßen- und Stadtbahnen bevorzugt werden sollen.
  • routingPreference (optional) gibt Präferenzen für Routen mit öffentlichen Verkehrsmitteln an. Mit dieser Option können Sie die zurückgegebenen Optionen beeinflussen, anstatt die standardmäßige beste Route der API zu verwenden. Dieses Feld kann nur angegeben werden, wenn die Anfrage einen API-Schlüssel enthält. Folgende Werte sind zulässig:
    • FEWER_TRANSFERS gibt an, dass die berechnete Route möglichst wenige Umstiege beinhalten soll.
    • LESS_WALKING gibt an, dass die berechnete Route möglichst wenige Gehstrecken enthalten soll.

Hier sehen Sie ein DirectionsRequest-Beispiel für eine Route mit öffentlichen Verkehrsmitteln:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Optionen für Kraftfahrzeuge

Mit dem Objekt DrivingOptions können Sie Routenoptionen für Wegbeschreibungen angeben.

Das Objekt DrivingOptions enthält die folgenden Felder:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Erläuterungen zu den Feldern:

  • departureTime (erforderlich, damit das Objektliteral drivingOptions gültig ist) gibt die gewünschte Startzeit als Date-Objekt an. Für den Wert muss die aktuelle Zeit oder eine Zeit in der Zukunft angegeben werden. Er darf nicht in der Vergangenheit liegen. (Die API wandelt alle entsprechenden Angaben in UTC um, um eine einheitliche Verarbeitung in allen Zeitzonen sicherzustellen.) Wenn Sie eine Lizenz für die Google Maps Platform-Premiumoption haben und departureTime in die Anfrage einbeziehen, gibt die API die beste Route angesichts der zu diesem Zeitpunkt zu erwartenden Verkehrslage zurück und schließt die voraussichtliche Reisezeit (duration_in_traffic) in die Antwort ein. Wenn Sie keine Startzeit angeben, drivingOptions also nicht in der Anfrage enthalten ist, wird eine passende Route zurückgegeben, ohne die Verkehrslage zu berücksichtigen.
  • trafficModel (optional) gibt die Annahmen an, die bei der Berechnung der Reisezeit verwendet werden sollen. Diese Einstellung wirkt sich auf den Wert für die voraussichtliche Reisezeit aus, der in der Antwort im Feld duration_in_traffic zurückgegeben und anhand bisheriger Durchschnittswerte berechnet wird. Die Standardeinstellung ist bestguess. Folgende Werte sind zulässig:
    • bestguess (Standardwert) gibt an, dass die zurückgegebene duration_in_traffic die beste Schätzung der Reisezeit sein sollte. Dazu werden Verlaufs- und Echtzeitdaten zur Verkehrslage herangezogen. Die aktuelle Verkehrslage wird umso stärker gewichtet, je näher die departureTime rückt.
    • pessimistic gibt an, dass die zurückgegebene duration_in_traffic länger sein sollte als die tatsächliche Reisezeit an den meisten Tagen. An Tagen mit besonders schlechter Verkehrslage kann dieser Wert jedoch überschritten werden.
    • optimistic gibt an, dass die zurückgegebene duration_in_traffic an den meisten Tagen kürzer als die tatsächliche Reisezeit sein dürfte. An Tagen mit besonders guter Verkehrslage kann dieser Wert jedoch unterschritten werden.

Hier sehen Sie ein DirectionsRequest-Beispiel für eine Kraftfahrzeugroute:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Einheitensysteme

Standardmäßig wird für die Berechnung und Anzeige von Routen das Einheitensystem des Ausgangslands bzw. der Ausgangsregion verwendet. Hinweis: Bei Ausgangsorten, für die Breitengrad-/Längengradkoordinaten anstelle von Adressen angegeben werden, werden standardmäßig immer metrische Einheiten verwendet. Bei einer Route von „Chicago, IL“ nach „Toronto, ONT“ werden die Ergebnisse also in Meilen angezeigt, für die Rückfahrt aber in Kilometern. Sie können das Einheitensystem überschreiben, indem sie in der Anfrage explizit ein anderes System festlegen. Folgende UnitSystem-Werte sind zulässig:

  • UnitSystem.METRIC gibt an, dass das metrische System verwendet werden soll. Entfernungen werden in Kilometern angegeben.
  • UnitSystem.IMPERIAL gibt an, dass das imperiale (englische) System verwendet werden soll. Entfernungen werden in Meilen angegeben.

Hinweis: Die Einstellung für das Einheitensystem wirkt sich nur auf den Text aus, den der Nutzer sieht. Das Routenergebnis beinhaltet auch Werte für Entfernungen, die dem Nutzer nicht angezeigt werden. Diese werden immer in Metern ausgedrückt.

Gewichtung nach Region

Der „Directions“-Dienst der Google Maps API gibt Adressergebnisse zurück, die sich nach der Domain (Region oder Land) richten, von der Sie das JavaScript Bootstrap geladen haben. Da die meisten Nutzer https://maps.googleapis.com/ laden, wird die USA implizit als Domain festgelegt. Wenn Sie die Bootstrap-URL von einer anderen unterstützten Domain aus laden, erhalten Sie Ergebnisse, die von dieser Domain beeinflusst werden. So kann die Suche nach „San Francisco“ in Anwendungen, die https://maps.googleapis.com/ laden (USA), andere Ergebnisse als in Anwendungen, die http://maps.google.es/ laden (Spanien), liefern.

Sie können auch den region-Parameter verwenden, damit der „Directions“-Dienst Ergebnisse liefert, die nach Region gewichtet sind. Der Parameter entspricht dem Regionscode, angegeben als zweistelliges (nicht numerisches) untergeordnetes Unicode-Tag für Regionen. In den meisten Fällen sind diese Tags direkt dem zweistelligen Ländercode der Top-Level-Domain (ccTLD) zugeordnet, z. B. „uk“ in „co.uk“. In einigen Fällen unterstützt das region-Tag auch ISO-3166-1-Codes, die sich teilweise von den ccTLD-Werten unterscheiden, z. B. „GB“ für Großbritannien.

Wenn Sie den region-Parameter verwenden:

  • Geben Sie nur ein Land oder eine Region an. Zusätzliche Werte werden ignoriert und können dazu führen, dass die Anfrage fehlschlägt.
  • Verwenden Sie nur zweistellige untergeordnete Tags für Regionen (Unicode-CLDR-Format). Alle anderen Eingaben führen zu Fehlern.

Die Gewichtung nach Region wird nur für Länder und Regionen unterstützt, die Routen unterstützen. Unter Details zur Google Maps Platform-Abdeckung finden Sie Informationen zur internationalen Abdeckung für die Directions API.

Routen rendern

Wenn mit der route()-Methode eine Routenanfrage an den DirectionsService gestartet wird, muss eine Callback-Funktion übergeben werden, die nach Abschluss der Dienstanfrage ausgeführt wird. Die Callback-Funktion gibt ein DirectionsResult und einen DirectionsStatus-Code als Antwort zurück.

Status von Routenanfragen

Für DirectionsStatus können folgende Werte zurückgegeben werden:

  • OK gibt an, dass die Antwort ein gültiges DirectionsResult enthält.
  • NOT_FOUND gibt an, dass mindestens einer der Orte, die in der Anfrage als Startort, Zielort oder Wegpunkt angegeben wurden, nicht geocodiert werden konnte.
  • ZERO_RESULTS gibt an, dass keine Route zwischen Start- und Zielort gefunden werden konnte.
  • MAX_WAYPOINTS_EXCEEDED gibt an, dass zu viele DirectionsWaypoint-Felder in der DirectionsRequest angegeben wurden. Weitere Informationen finden Sie unten im Abschnitt Limits und Einschränkungen für Wegpunkte.
  • MAX_ROUTE_LENGTH_EXCEEDED gibt an, dass die angeforderte Route zu lang ist und nicht verarbeitet werden kann. Dieser Fehler tritt auf, wenn komplexere Routen zurückgegeben werden. Verringern Sie die Anzahl der Wegpunkte, Abzweigungen oder Anleitungen.
  • INVALID_REQUEST gibt an, dass der DirectionsRequest ungültig war. Die häufigste Ursache für diesen Fehlercode sind Anfragen ohne Start- oder Zielort oder Anfragen für öffentliche Verkehrsmittel, die Wegpunkte enthalten.
  • OVER_QUERY_LIMIT gibt an, dass die Webseite zu viele Anfragen innerhalb des zulässigen Zeitraums gesendet hat.
  • REQUEST_DENIED gibt an, dass die Webseite den „Directions“-Dienst nicht verwenden darf.
  • UNKNOWN_ERROR gibt an, dass eine Routenanfrage aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Möglicherweise ist sie beim nächsten Versuch erfolgreich.

Sie sollten sich diesen Wert ansehen, bevor das Ergebnis verarbeitet wird, um sicherzustellen, dass die Routenanfrage gültige Ergebnisse geliefert hat.

„DirectionsResult“-Objekt anzeigen

Das DirectionsResult beinhaltet das Ergebnis der Routenanfrage. Sie können es entweder selbst verarbeiten oder an ein DirectionsRenderer-Objekt übergeben, das das Ergebnis automatisch auf der Karte rendert.

Um einen DirectionsRenderer für ein DirectionsResult zu verwenden, müssen Sie Folgendes tun:

  1. Erstellen Sie ein DirectionsRenderer-Objekt.
  2. Rufen Sie setMap() im Renderer auf, um ihn an die übergebene Karte zu binden.
  3. Rufen Sie setDirections() im Renderer auf und übergeben Sie das DirectionsResult wie oben erwähnt. Der Renderer ist ein MVCObject. Daher erkennt er automatisch Änderungen an seinen Eigenschaften und aktualisiert die Karte, wenn sich die zugewiesenen Routen geändert haben.

Im folgenden Beispiel wird die Route zwischen zwei Orten an der Route 66 berechnet. Dabei werden Start- und Zielort durch die "start"- und "end"-Werte in den Drop-down-Listen definiert. Der DirectionsRenderer rendert die Polylinie zwischen den angegebenen Orten und die Markierungen für Startort, Zielort und alle Wegpunkte, falls vorhanden.

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

Im HTML-Textkörper:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

Beispiel ansehen

Im folgenden Beispiel werden Routen von Haight-Ashbury nach Ocean Beach in San Francisco, CA, USA für verschiedene Mobilitätsformen angezeigt:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

Im HTML-Textkörper:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

Beispiel ansehen

Ein DirectionsRenderer rendert nicht nur die Polylinie und alle zugewiesenen Markierungen, sondern bei Bedarf auch die Routenschritte in Textform. Dazu rufen Sie setPanel() im DirectionsRenderer auf und übergeben das <div>-Element, in dem diese Informationen angezeigt werden sollen. So wird auch sichergestellt, dass Sie die erforderlichen Copyright-Hinweise und alle Warnungen für das Ergebnis anzeigen.

Für die Routen in Textform wird die Spracheinstellung des Browsers verwendet oder die Sprache, die beim Laden des API-JavaScript-Codes mit dem language-Parameter festgelegt wurde. Weitere Informationen finden Sie unter Karte lokalisieren. Bei Routen für öffentliche Verkehrsmittel wird die Zeit in der Zeitzone der jeweiligen Haltestelle angezeigt.

Das folgende Beispiel ist mit dem vorherigen identisch, beinhaltet jedoch einen <div>-Bereich, in dem die Route angezeigt wird:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

Im HTML-Textkörper:

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

Beispiel ansehen

„DirectionsResult“-Objekt

Wenn Sie eine Routenanfrage an den DirectionsService senden, erhalten Sie eine Antwort, die aus einem Statuscode und einem Ergebnis (einem DirectionsResult-Objekt) besteht. DirectionsResult ist ein Objektliteral mit den folgenden Feldern:

  • geocoded_waypoints[] enthält ein Array mit DirectionsGeocodedWaypoint-Objekten, von denen jedes Details zum Geocoding von Startort, Zielort und Wegpunkten enthält.
  • routes[] enthält ein Array mit DirectionsRoute-Objekten. Jede Route gibt einen Weg an, der den Start- und Zielort aus der DirectionsRequest miteinander verbindet. Generell wird für eine Anfrage nur eine Route zurückgegeben, es sei denn, für das Feld provideRouteAlternatives der Anfrage wurde true festgelegt, damit mehrere Routen zurückgegeben werden können.

Hinweis: Die Eigenschaft via_waypoint wurde in alternativen Routen eingestellt. Version 3.27 ist die letzte Version der API, die zusätzliche Wegpunkte in alternativen Routen hinzufügt. Ab Version 3.28 der API können Sie weiterhin ziehbare Routen über den „Directions“-Dienst implementieren. Dazu müssen Sie das Ziehen alternativer Routen deaktivieren. Nur die Hauptroute sollte ziehbar sein. Nutzer können die Hauptroute ziehen, bis sie einer alternativen Route entspricht.

Routen mit geocodierten Wegpunkten

Ein DirectionsGeocodedWaypoint enthält Details zum Geocoding von Startort, Zielort und Wegpunkten.

DirectionsGeocodedWaypoint ist ein Objektliteral mit folgenden Feldern:

  • geocoder_status gibt den Statuscode des Geocoding-Vorgangs an. Das Feld kann folgende Werte enthalten:
    • "OK" gibt an, dass die Adresse ohne Fehler geparst und mindestens ein Geocode zurückgegeben wurde.
    • "ZERO_RESULTS" gibt an, dass die Geocodierung erfolgreich war, aber keine Ergebnisse zurückgegeben wurden. Dieser Status kann ausgegeben werden, wenn dem Geocoder ein nicht vorhandenes address-Element übergeben wurde.

  • partial_match gibt an, dass der Geocoder keine genaue Übereinstimmung für die ursprüngliche Anfrage zurückgegeben hat, obwohl ein Teil der angeforderten Adresse zugeordnet werden konnte. Wir empfehlen, die ursprüngliche Anfrage auf Tippfehler und/oder Vollständigkeit zu prüfen.

    Teilweise Übereinstimmungen treten am häufigsten bei Adressen auf, die nicht in dem Ort vorhanden sind, der in der Anfrage übergeben wird. Sie werden unter Umständen auch zurückgegeben, wenn eine Anfrage mit mehreren Adressen in einem Ort übereinstimmt. Wird „Henr St, Bristol, UK“ angefragt, wird z. B. eine teilweise Übereinstimmung für die Henry Street und die Henrietta Street zurückgegeben. Enthält eine Anfrage eine Adresskomponente mit Tippfehler, wird vom Geocoding-Dienst möglicherweise eine andere Adresse vorgeschlagen. Solche Vorschläge werden auch als teilweise Übereinstimmung gekennzeichnet.

  • place_id ist eine eindeutige Kennung für einen Ort, die mit anderen Google APIs verwendet werden kann. Sie können z. B. die place_id mit der Google Places API-Bibliothek verwenden, um Details zu einem lokalen Unternehmen wie Telefonnummer, Öffnungszeiten oder Nutzerrezensionen abzurufen. Weitere Informationen finden Sie unter Orts-IDs.
  • types[] ist ein Array, das den Typ des zurückgegebenen Ergebnisses angibt. Das Array enthält eine Reihe mit null oder mehr Tags, mit denen der Typ des im Ergebnis zurückgegebenen Elements bestimmt wird. Wird der Geocode für Chicago angefordert, wird z. B. ein Element vom Typ „locality“ zurückgegeben, was bedeutet, dass Chicago ein Ort ist, sowie das Element „political“, was bedeutet, dass Chicago eine politische Einheit ist.

Routen

Hinweis: Das alte DirectionsTrip-Objekt wurde in DirectionsRoute umbenannt. Eine Route bezieht sich nun auf die gesamte Reise von Start bis Ziel und nicht mehr nur auf einen Abschnitt einer übergeordneten Reise.

DirectionsRoute enthält ein einzelnes Ergebnis für den angegebenen Start- und Zielort. Die Route kann aus einem oder mehreren Abschnitten bestehen (Typ DirectionsLeg), je nachdem, ob Wegpunkte angegeben wurden. Darüber hinaus enthält die Route Copyright-Hinweise und Warnungen, die dem Nutzer zusätzlich zu den Routeninformationen angezeigt werden müssen.

DirectionsRoute ist ein Objektliteral mit folgenden Feldern:

  • legs[] enthält ein Array mit DirectionsLeg-Objekten, von denen jedes Informationen zu einem Abschnitt zwischen zwei Orten der angegebenen Route beinhaltet. Für jeden angegebenen Wegpunkt oder Zielort ist ein separater Routenabschnitt vorhanden. Routen ohne Wegpunkte enthalten genau ein DirectionsLeg. Jeder Abschnitt besteht aus einer Reihe von DirectionSteps.
  • waypoint_order enthält ein Array, das die Reihenfolge der Wegpunkte in der berechneten Route angibt. Das Array kann eine alternative Reihenfolge enthalten, wenn optimizeWaypoints: true bei dem DirectionsRequest übergeben wurde.
  • overview_path enthält ein Array mit LatLng-Werten, die einen angenäherten (geglätteten) Pfad der ermittelten Route darstellen.
  • overview_polyline enthält ein einzelnes points-Objekt mit einer codierten Polylinie. Die Polylinie ist der annähernde (geglättete) Pfad der ermittelten Route.
  • bounds enthält einen LatLngBounds-Wert, der die Grenzen der Polylinie entlang der gegebenen Route angibt.
  • copyrights enthält den Copyright-Text, der für diese Route angezeigt werden soll.
  • warnings[] enthält ein Array mit Warnungen, die zusammen mit der Route angezeigt werden müssen. Wenn Sie das bereitgestellte DirectionsRenderer-Objekt nicht verwenden, müssen Sie diese Warnungen selbst verarbeiten und darstellen.
  • fare enthält den Gesamtfahrpreis (die gesamten Fahrkartenkosten) für diese Route. Diese Eigenschaft wird nur für Anfragen für Routen mit öffentlichen Verkehrsmitteln zurückgegeben und nur, wenn für alle Abschnitte mit öffentlichen Verkehrsmitteln Fahrpreisinformationen zur Verfügung stehen. Folgende Informationen werden zurückgegeben:

Routenabschnitte

Hinweis: Das alte DirectionsRoute-Objekt wurde in DirectionsLeg umbenannt.

DirectionsLeg definiert einen einzelnen Abschnitt der ermittelten Route zwischen Start- und Zielort. Routen ohne Wegpunkte bestehen aus einem einzelnen Abschnitt. Routen mit Wegpunkten enthalten zusätzliche Abschnitte in entsprechender Anzahl.

DirectionsLeg ist ein Objektliteral mit folgenden Feldern:

  • steps[] enthält ein Array mit DirectionsStep-Objekten mit Informationen zu den einzelnen Schritten eines Abschnitts.

  • distance gibt die Gesamtstrecke, die in diesem Abschnitt zurückgelegt wird, als Distance-Objekt mit folgender Form an:

    • value gibt die Strecke in Metern an.
    • text enthält einen String zur Darstellung der Strecke. Er wird standardmäßig in den Einheiten angezeigt, die am Startort verwendet werden. Liegt dieser in den USA, werden z. B. Meilen verwendet. Sie können das Einheitensystem überschreiben, indem Sie in der ursprünglichen Anfrage ein spezifisches UnitSystem festlegen. Unabhängig davon, welches Einheitensystem Sie verwenden, wird der Wert im Feld distance.value immer in Metern angegeben.

    Diese Felder können leer sein, wenn die Strecke nicht bekannt ist.

  • duration gibt die Gesamtdauer für diesen Abschnitt als Duration-Objekt mit folgender Form an:

    • value gibt die Dauer in Sekunden an.
    • text enthält einen String zur Darstellung der Dauer.

    Diese Felder können leer sein, wenn die Dauer nicht bekannt ist.

  • duration_in_traffic gibt die Gesamtdauer dieses Abschnitts unter Berücksichtigung der aktuellen Verkehrslage an. duration_in_traffic wird nur zurückgegeben, wenn alle der folgenden Bedingungen erfüllt sind:

    • Die Anfrage enthält keine Wegpunkte mit Aufenthalt. Das heißt, sie enthält keine Wegpunkte, wo stopover den Wert true hat.
    • Die Anfrage bezieht sich speziell auf Kraftfahrzeugrouten – mode ist auf driving gesetzt.
    • departureTime ist im Feld drivingOptions in der Anfrage enthalten.
    • Für die angeforderte Route sind Informationen zur Verkehrslage verfügbar.

    duration_in_traffic enthält die folgenden Felder:

    • value gibt die Dauer in Sekunden an.
    • text enthält eine menschenlesbare Darstellung der Dauer.
  • arrival_time enthält die voraussichtliche Ankunftszeit für diesen Abschnitt. Diese Eigenschaft wird nur bei Anfragen für öffentliche Verkehrsmittel zurückgegeben. Das Ergebnis wird als Time-Objekt mit drei Eigenschaften zurückgegeben:
    • value ist die Zeit und wird als JavaScript-Date-Objekt angegeben.
    • text ist die als String angegebene Zeit. Sie wird in der Zeitzone der Haltestelle angegeben.
    • time_zone enthält die Zeitzone dieser Haltestelle. Dabei wird der entsprechende Wert aus der IANA-Zeitzonendatenbank verwendet, z. B. „Europe/Paris“.
  • departure_time enthält die voraussichtliche Abfahrtszeit für diesen Abschnitt und wird als Time-Objekt angegeben. departure_time ist nur für Routen mit öffentlichen Verkehrsmitteln verfügbar.
  • start_location enthält den LatLng-Wert des Startorts dieses Abschnitts. Der „Directions“-Webdienst berechnet Routen zwischen Orten, indem er die nächstgelegene Mobilitätsoption (in der Regel eine Straße) am Start- und Endpunkt verwendet. Daher kann start_location vom angegebenen Startpunkt dieses Abschnitts abweichen, wenn es beispielsweise keine Straße in der Nähe des Startpunkts gibt.
  • end_location enthält den LatLng-Wert des Zielorts dieses Abschnitts. Der DirectionsService berechnet Routen zwischen Orten, indem er die nächstgelegene Mobilitätsoption (in der Regel eine Straße) am Start- und Endpunkt verwendet. Daher kann end_location vom angegebenen Zielpunkt dieses Abschnitts abweichen, wenn es beispielsweise keine Straße in der Nähe des Zielpunkts gibt.
  • start_address enthält die menschenlesbare Adresse für den Start des Abschnitts, in der Regel die Straße.

    Der Inhalt ist so zu lesen, wie er ist. Die formatierte Adresse darf nicht programmatisch geparst werden.
  • end_address enthält die menschenlesbare Adresse für das Ende des Abschnitts, in der Regel die Straße.

    Der Inhalt ist so zu lesen, wie er ist. Die formatierte Adresse darf nicht programmatisch geparst werden.

Routenschritte

Ein DirectionsStep ist die kleinste Einheit einer Route – ein einzelner Schritt, der eine spezifische, einzelne Anweisung auf der Route beschreibt, z. B. „Rechts abbiegen auf Volksgartenstraße“. Er enthält nicht nur die Anweisung, sondern es werden auch Informationen zur Entfernung und Dauer für den nächsten Schritt angezeigt. Enthält der Schritt „Weiter auf A15“ die Angaben „37 Kilometer“ und „40 Minuten“, bedeutet das z. B., dass der nächste Schritt 37 Kilometer und 40 Minuten entfernt ist.

Wenn Sie mit dem „Directions“-Dienst nach Routen für öffentliche Verkehrsmittel suchen, enthält das Array mit Schritten zusätzliche spezifische Informationen zu öffentlichen Verkehrsmitteln in Form eines transit-Objekts. Beinhaltet die Route mehrere Mobilitätsformen, werden detaillierte Anleitungen für Geh- oder Fahrstrecken in einem steps[]-Array bereitgestellt. Angenommen, eine Gehstrecke enthält eine Wegbeschreibung vom Start- zum Zielort: „Bis Ecke Hauptstraße/Lindenallee gehen“. Dann umfasst der Schritt eine detaillierte Beschreibung der Gehstrecke für diese Route im steps[]-Array, etwa „Nach Nordwesten gehen“, „Links auf Uferstraße abbiegen“ und „Links auf Hauptstraße abbiegen“.

DirectionsStep ist ein Objektliteral mit folgenden Feldern:

  • instructions enthält eine Anleitung für diesen Schritt in einem Textstring.
  • distance enthält die Strecke zwischen diesem und dem nächsten Schritt als Distance-Objekt. Weitere Informationen finden Sie in der Beschreibung zu DirectionsLeg oben. Dieses Feld kann leer sein, wenn die Strecke nicht bekannt ist.
  • duration enthält eine Schätzung der Zeit, die zum Abschließen des Schritts bis zum nächsten Schritt benötigt wird (als Duration-Objekt). Weitere Informationen finden Sie in der Beschreibung zu DirectionsLeg oben. Dieses Feld kann leer sein, wenn die Dauer nicht bekannt ist.
  • start_location enthält den geocodierten LatLng-Wert des Startpunkts dieses Schritts.
  • end_location enthält den geocodierten LatLng-Wert des Endpunkts dieses Schritts.
  • polyline enthält ein einzelnes points-Objekt mit einer codierten Polylinie zum Darstellen des Schritts. Die Polylinie ist der annähernde (geglättete) Pfad des Schritts.
  • steps[] ist ein DirectionsStep-Objektliteral, das detaillierte Anleitungen für Geh- und Fahrstrecken in Routen für öffentliche Verkehrsmittel enthält. Teilschritte sind nur für Routen für öffentliche Verkehrsmittel verfügbar.
  • travel_mode enthält den in diesem Schritt verwendeten TravelMode. Routen für öffentliche Verkehrsmittel können Gehstrecken und Strecken mit öffentlichen Verkehrsmitteln enthalten.
  • path enthält ein Array mit LatLngs-Werten zur Beschreibung des Verlaufs dieses Schritts.
  • transit enthält spezifische Informationen zu öffentlichen Verkehrsmitteln, z. B. Ankunfts- und Abfahrtszeiten sowie den Namen der ÖPNV-Linie.

Spezifische Informationen zu öffentlichen Verkehrsmitteln

Bei Routen für öffentliche Verkehrsmittel werden zusätzliche Informationen zurückgegeben, die für andere Mobilitätsformen nicht relevant sind. Diese zusätzlichen Eigenschaften werden über das Objekt TransitDetails bereitgestellt, das als Eigenschaft von DirectionsStep zurückgegeben wird. Über das Objekt TransitDetails können Sie, wie unten beschrieben, auf zusätzliche Informationen für die Objekte TransitStop, TransitLine, TransitAgency und VehicleType zugreifen.

Details zu öffentlichen Verkehrsmitteln

Das Objekt TransitDetails stellt die folgenden Eigenschaften bereit:

  • arrival_stop enthält ein TransitStop-Objekt, das die Zielhaltestelle mit den folgenden Eigenschaften darstellt:
    • name ist der Name der Haltestelle, z. B. „Union Square“.
    • location ist der Standort der Haltestelle, angegeben als LatLng-Wert.
  • departure_stop enthält ein TransitStop-Objekt, das die Starthaltestelle darstellt.
  • arrival_time enthält die Ankunftszeit und wird als Time-Objekt mit drei Eigenschaften angegeben:
    • value ist die Zeit und wird als JavaScript-Date-Objekt angegeben.
    • text ist die als String angegebene Zeit. Sie wird in der Zeitzone der Haltestelle angegeben.
    • time_zone enthält die Zeitzone dieser Haltestelle. Dabei wird der entsprechende Wert aus der IANA-Zeitzonendatenbank verwendet, z. B. „Europe/Paris“.
  • departure_time enthält die Abfahrtszeit und wird als Time-Objekt angegeben.
  • headsign gibt die Fahrtrichtung dieser Linie an, die auf dem Fahrzeug oder an der Haltestelle ausgewiesen ist. Oft ist das der Name der Endhaltestelle.
  • headway (sofern verfügbar) gibt die erwartete Anzahl Sekunden zwischen Abfahrten von derselben Haltestelle zu dieser Zeit an. Bei einem headway-Wert von 600 wäre z. B. mit einer Wartezeit von 10 Minuten zu rechnen, wenn man einen Bus verpasst.
  • line enthält ein TransitLine-Objektliteral, das Informationen zu der in diesem Schritt verwendeten ÖPNV-Linie enthält. TransitLine gibt Namen und Betreiber der Linie sowie andere Eigenschaften, die in der TransitLine-Referenzdokumentation beschrieben werden, an.
  • num_stops enthält die Anzahl der Haltestellen in diesem Schritt. Dabei wird die Zielhaltestelle mitgezählt, die Starthaltestelle aber nicht. Wenn Sie z. B. an Haltestelle A abfahren, die Haltestellen B und C durchfahren und bei Haltestelle D aussteigen, wird für num_stops 3 zurückgegeben.

ÖPNV-Linie

Das TransitLine-Objekt umfasst folgende Eigenschaften:

  • name enthält den vollständigen Namen der ÖPNV-Linie, z. B. „Hauptbahnhof“ oder „Altona“.
  • short_name enthält den Kurznamen der ÖPNV-Linie. Das ist normalerweise eine Nummer wie „2“ oder „M14“.
  • agencies ist ein Array mit einem einzelnen TransitAgency-Objekt. Das TransitAgency-Objekt stellt Informationen zum Betreiber der Linie bereit, darunter folgende Eigenschaften:
    • name enthält den Namen des Betreibers.
    • phone enthält die Telefonnummer des Betreibers.
    • url enthält die URL des Betreibers.

    Hinweis: Wenn Sie Routen mit öffentlichen Verkehrsmitteln manuell rendern, statt das DirectionsRenderer-Objekt zu verwenden, müssen die Namen und URLs der Betreiber für die Ergebnisse angezeigt werden.

  • url enthält eine URL für die ÖPNV-Linie, die vom Betreiber bereitstellt wird.
  • icon enthält eine URL für das Symbol, das dieser Linie zugeordnet ist. In den meisten Städten sind das generische Symbole, die je nach Fahrzeugtyp variieren. Manche ÖPNV-Linien, z. B. die New Yorker U-Bahnen, haben spezifische Symbole.
  • color enthält die Farbe, die üblicherweise für die Beschilderung dieser Linie verwendet wird. Sie wird als hexadezimaler String angegeben, z. B. #FF0033.
  • text_color enthält die Textfarbe, die üblicherweise für die Beschilderung dieser Linie verwendet wird. Sie wird als hexadezimaler String angegeben.
  • vehicle enthält ein Vehicle-Objekt mit folgenden Eigenschaften:
    • name enthält den Namen des Fahrzeugs, das auf dieser Linie eingesetzt wird, z. B. „U-Bahn“.
    • type enthält den Typ des Fahrzeugs, das auf dieser Linie eingesetzt wird. Eine vollständige Liste der unterstützten Werte finden Sie in der Dokumentation zum Fahrzeugtyp.
    • icon enthält eine URL für das Symbol, das diesem Fahrzeugtyp normalerweise zugeordnet ist.
    • local_icon enthält die URL für das Symbol, das diesem Fahrzeugtyp zugeordnet ist, und basiert auf der Beschilderung.

Fahrzeugtyp

Das VehicleType-Objekt umfasst folgende Eigenschaften:

Wert Definition
VehicleType.RAIL Bahn
VehicleType.METRO_RAIL Stadtbahn
VehicleType.SUBWAY U-Bahn
VehicleType.TRAM Straßenbahn
VehicleType.MONORAIL Einschienenbahn
VehicleType.HEAVY_RAIL Eisenbahn
VehicleType.COMMUTER_TRAIN Schnellbahn
VehicleType.HIGH_SPEED_TRAIN Schnellzug
VehicleType.BUS Bus
VehicleType.INTERCITY_BUS Fernbus
VehicleType.TROLLEYBUS Oberleitungsbus
VehicleType.SHARE_TAXI Sammeltaxis sind eine Art Bus, bei dem Fahrgäste überall auf der Strecke ein- und aussteigen können.
VehicleType.FERRY Fähre
VehicleType.CABLE_CAR Ein Fahrzeug, das über Kabel betrieben wird, normalerweise am Boden. Luftseilbahnen haben den Typ VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Eine Luftseilbahn.
VehicleType.FUNICULAR Ein Fahrzeug, das mit einem Kabel eine starke Steigung hinaufgezogen wird. Eine Standseilbahn besteht normalerweise aus zwei Wagen, wobei jeder als Gegengewicht für den anderen dient.
VehicleType.OTHER Bei allen anderen Fahrzeugen wird dieser Typ zurückgegeben.

„DirectionsResults“ analysieren

Die DirectionsResults-Komponenten (DirectionsRoute, DirectionsLeg, DirectionsStep und TransitDetails) können beim Parsen von Routenantworten analysiert und verwendet werden.

Wichtig: Wenn Sie Routen mit öffentlichen Verkehrsmitteln manuell rendern, statt das DirectionsRenderer-Objekt zu verwenden, müssen die Namen und URLs der Betreiber für die Ergebnisse angezeigt werden.

Im folgenden Beispiel wird die Fußgängerroute zu bestimmten Touristenattraktionen in New York City dargestellt. Wir analysieren die DirectionsSteps der Route, um Markierungen für die einzelnen Schritte und ein InfoWindow mit Textanweisungen für den jeweiligen Schritt einzufügen.

Hinweis: Da eine Fußgängerroute berechnet wird, werden Nutzern potenzielle Warnungen in einem separaten <div>-Bereich angezeigt.

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

Im HTML-Textkörper:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

Beispiel ansehen

Wegpunkte in Routen verwenden

Wie unter Routenanfragen erwähnt, können Sie beim Berechnen von Routen für Fußgänger, Radfahrer oder Autofahrer über den „Directions“-Dienst auch Wegpunkte (vom Typ DirectionsWaypoint) angeben. Für Routen mit öffentlichen Verkehrsmitteln werden Wegpunkte nicht unterstützt. Wenn Sie Wegpunkte angeben, verläuft die zurückgegebene Route durch die entsprechenden Orte.

Ein waypoint besteht aus folgenden Feldern:

  • location (erforderlich) gibt die Adresse des Wegpunkts an.
  • stopover (optional) gibt an, ob dieser Wegpunkt ein tatsächlicher Aufenthalt auf der Route ist (true) oder nur ein Ort, durch den die Route bevorzugt verlaufen soll (false). Aufenthalte sind standardmäßig true.

Standardmäßig berechnet der „Directions“-Dienst die Route über die Wegpunkte in der angegebenen Reihenfolge. Optional können Sie optimizeWaypoints: true in DirectionsRequest übergeben, damit der „Directions“-Dienst die Wegpunkte in eine effizientere Reihenfolge bringen kann, um die Route zu optimieren. Diese Optimierung ist eine Umsetzung des Rundreiseproblems. Die Route wird primär nach der Fahrzeit optimiert, es können aber auch andere Faktoren berücksichtigt werden, wie z. B. die Entfernung oder die Anzahl der Abzweige. Damit der „Directions“-Dienst die Route optimieren kann, müssen alle Wegpunkte als Aufenthalte definiert sein.

Wenn Sie den „Directions“-Dienst anweisen, die Reihenfolge der Wegpunkte zu optimieren, wird die Reihenfolge im Feld waypoint_order im DirectionsResult-Objekt zurückgegeben.

Im folgenden Beispiel werden Routen durch die USA mit verschiedenen Start-, End- und Wegpunkten berechnet. Durch Strg + Klicken können Sie mehrere Wegpunkte in der Liste gleichzeitig auswählen. Wir analysieren routes.start_address und routes.end_address, um den Text für den Start- und Endpunkt jeder Route zu erhalten.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;
index.js

Limits und Einschränkungen für Wegpunkte

Für Wegpunkte gelten die folgenden Nutzungslimits und Einschränkungen:

  • Bei Verwendung des „Directions“-Diensts in der Maps JavaScript API sind maximal 25 Wegpunkte plus Ausgangs- und Zielort zulässig. Die Limits gelten auch für den Directions API-Webdienst.
  • Für den Directions API-Webdienst sind maximal 25 Wegpunkte plus Ausgangs- und Zielort zulässig.
  • Für Kunden mit der Google Maps Platform-Premiumoption sind 25 Wegpunkte plus Ausgangs- und Zielort zulässig.
  • Für Routen mit öffentlichen Verkehrsmitteln werden Wegpunkte nicht unterstützt.

Ziehbare Routen

Nutzer können Routen für Radfahrer, Fußgänger und Autofahrer, die mithilfe eines DirectionsRenderer-Objekts angezeigt werden, dynamisch anpassen, wenn sie ziehbar sind. Dazu klicken sie die Pfade auf der Karte an und ziehen sie auf die gewünschten Positionen. Damit Nutzer Routen so anpassen können, müssen Sie die draggable-Eigenschaft des Renderers auf true setzen. Für Routen für öffentliche Verkehrsmittel ist diese Option nicht verfügbar.

Wenn Routen ziehbar sind, kann der Nutzer einen beliebigen Punkt auf dem Pfad (oder Wegpunkt) des gerenderten Ergebnisses anklicken bzw. antippen und an eine neue Position ziehen. Der DirectionsRenderer wird dynamisch aktualisiert, um den geänderten Pfad anzuzeigen. Lässt der Nutzer los, wird der Karte ein Zwischenwegpunkt hinzugefügt und durch eine kleine weiße Markierung gekennzeichnet. Wird ein Pfadsegment ausgewählt und verschoben, ändert sich der betreffende Abschnitt der Route. Beim Auswählen und Verschieben einer Wegpunktmarkierung (einschließlich Start- und Endpunkt) werden die Routenabschnitte geändert, die über diesen Wegpunkt verlaufen.

Da ziehbare Routen clientseitig angepasst und gerendert werden, sollten Sie das directions_changed-Ereignis im DirectionsRenderer beobachten und verarbeiten, damit eine Benachrichtigung ausgegeben wird, wenn der Nutzer die angezeigte Route ändert.

Mit folgendem Code wird eine Fahrt von Perth an der australischen Westküste nach Sydney an der Ostküste angezeigt. Dabei wird das directions_changed-Ereignis beobachtet, um die Gesamtstrecke aller Routenabschnitte zu aktualisieren.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
index.js
Beispiel ansehen

Testbeispiel