Es kann losgehen!

Bevor Sie mit der Entwicklung beginnen, lesen Sie bitte unsere Entwicklerdokumentation.

Die Google Maps Directions API aktivieren

Zum Einstieg führen wir Sie durch die Google Developers Console, wo Sie vorab Folgendes tun müssen:

  1. Ein Projekt erstellen oder auswählen
  2. Die Google Maps Directions API aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Entwickler-Leitfaden

Die Google Maps Directions API ist ein Dienst, mit dem Wegbeschreibungen zwischen Standorten per HTTP-Anforderung berechnet werden können.

Dieser Dienst steht auch als Teil der clientseitigen Google Maps JavaScript API oder zur Verwendung auf Serverseite mit dem Java Client, Python Client, Go Client und Node.js Client for Google Maps Services zur Verfügung. Hinweis: Unabhängig davon, wie oft Sie den Dienst nutzen, gelten dieselben täglichen Nutzungsbeschränkungen. Die Anforderungen pro Tag werden als die Summe der clientseitigen und serverseitigen Abfragen berechnet.

Dieses Dokument richtet sich an Entwickler von Websites und mobilen Anwendungen, die Wegbeschreibungen in Karten berechnen möchten, die von einer der Google Maps APIs bereitgestellt werden. Es enthält eine Einführung zur Verwendung der API und Informationen zu den verfügbaren Parametern.

Einführung

In diesem Video wird gezeigt, wie die Google Maps Directions API zur Navigation verwendet wird. Das Video enthält auch eine Anleitung zur Verwendung Ihres Servers als Proxy für den Webdienst, damit bei Verwendung der API in einer mobilen App Ihr API-Schlüssel geschützt bleibt.

Mit Directions API können Sie Folgendes:

  • Nach Wegbeschreibungen für verschiedene Transportmittel suchen, darunter Beschreibungen für öffentliche Verkehrsmittel, Kraftfahrzeuge, Fußgänger oder Radfahrer.
  • Mehrteilige Wegbeschreibungen ausgeben, wenn eine Reihe von Wegpunkten angegeben wird.
  • Ausgangspunkte, Ziele und Wegpunkte als Zeichenfolgen (z. B. „Chicago, IL“ oder „Darwin, NT, Australien“), als Koordinaten (Längen- und Breitengrad) oder als Orts-ID angeben.

Die Berechnung von Wegbeschreibungen ist eine aufwändige Aufgabe. Berechnen Sie bekannte Adressen daher mithilfe des hier vorgestellten Dienstes soweit möglich im Voraus und speichern Sie die Ergebnisse in einem Cache.

Hinweis: Dieser Dienst ist nicht dafür konzipiert, in Echtzeit auf Nutzereingaben zu reagieren. Hinweise zu dynamischen Berechnungen (z. B. in einem UI-Element) erhalten Sie in der Dokumentation zum Google Maps JavaScript API Directions Service.

Bevor Sie mit der Durchführung von Entwicklungsaufgaben mit der Directions API beginnen, informieren Sie sich über die Authentifizierungsanforderungen (Sie benötigen einen API-Schlüssel) und die API-Nutzungsbeschränkungen.

Wegbeschreibungsanforderungen

Eine Google Maps Directions API-Anforderung weist folgendes Format auf:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Dabei kann outputFormat einen der folgenden Werte haben:

  • json (empfohlen) gibt die Ausgabe in JavaScript Object Notation (JSON) an
  • xml gibt die Ausgabe in XML an

Hinweis: URLs müssen ordnungsgemäß codiert sein, um gültig zu sein, und sind auf 8192 Zeichen für alle Webdienste beschränkt. Beachten Sie diese Beschränkung beim Erstellen Ihrer URLs.

HTTPS oder HTTP

Sicherheit ist wichtig und sofern möglich sollte HTTPS verwendet werden. Dies gilt insbesondere für Anwendungen, die in den Anforderungen persönliche Daten von Nutzern wie Standortangaben enthalten. Mit der HTTPS-Verschlüsselung wird Ihre Anwendung sicherer und ist besser vor Spionage und unbefugten Eingriffen geschützt.

Ist HTTPS nicht möglich, verwenden Sie für den Zugriff auf die Google Maps Directions API über HTTP Folgendes:

http://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Anforderungsparameter

Einige Parameter sind erforderlich, während andere optional verwendet werden können. Standardmäßig werden alle Parameter in URLs durch ein kaufmännisches Und (&) getrennt. Die Liste der Parameter und deren mögliche Werte sind unten aufgeführt.

Erforderliche Parameter

  • origin — die Adresse, der Textwert mit Längen- und Breitengrad oder die Orts-ID, von der/dem aus die Wegbeschreibung berechnet werden soll.
    • Wenn Sie eine Adresse als Zeichenfolge übergeben, geocodiert der Directions-Dienst die Zeichenfolge und wandelt sie in Längengrad- und Breitengradkoordinaten um, um so die Wegbeschreibungen zu berechnen. Diese Koordinate kann sich von der Koordinate unterscheiden, die durch die Google Maps Geocoding API zurückgegeben wird. Sie kann bspw. einen Gebäudeeingang anstelle der Gebäudemitte bezeichnen.
      origin=24+Sussex+Drive+Ottawa+ON
    • Wenn Sie Koordinaten übergeben, werden diese unverändert zur Berechnung der Wegbeschreibungen verwendet. Beachten Sie, dass sich zwischen den Werten für den Längen- und den Breitengrad kein Leerzeichen befinden darf.
      origin=41.43206,-81.38992
    • Orts-IDs muss place_id: vorangestellt sein. Die Orts-ID kann nur angegeben werden, wenn die Anforderung einen API-Schlüssel oder eine Google Maps APIs Premium Plan-Client-ID enthält. Sie können Orts-IDs mithilfe der Google Maps Geocoding API und der Google Places API (einschließlich automatischer Vervollständigung von Orten) abrufen. Ein Beispiel, in dem Orts-IDs aus der Autovervollständigung von Orten verwendet werden, finden Sie unter Autovervollständigung von Orten und Wegbeschreibungen. Weitere Informationen zu Orts-IDs finden Sie unter Orts-IDs – Übersicht.
      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
  • destination — die Adresse, der Textwert mit Längen- und Breitengrad oder die Orts-ID, bis zu der/dem die Wegbeschreibung berechnet werden soll. Die Optionen für den Parameter destination entsprechen den Optionen des oben beschriebenen Parameters origin.
  • key — der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für das Kontingentmanagement. So können Sie einen Schlüssel anfordern.

    Hinweis: Google Maps APIs Premium Plan-Kunden können entweder einen API-Schlüssel oder eine gültige Client-ID und eine digitale Signatur in Ihren Directions-Anforderungen verwenden. Lesen Sie weitere Informationen zu Authentifizierungsparametern für Premium Plan-Kunden.

Optionale Parameter

  • mode (Standard: driving) — gibt das Transportmittel an, auf dem die Berechnung der Wegbeschreibung basieren soll. Die gültigen Werte und weitere Einzelheiten zu Anforderungen finden Sie unter Transportmittel.
  • waypoints — gibt ein Array von Wegpunkten an. Wegpunkte sind bestimmte Orte, über die die Route geführt wird. Sie werden als Koordinaten (Längen- und Breitengrad), codierte Polylinien, Orts-IDs oder als Adressen angegeben, die geocodiert werden. Codierten Polylinien muss das Präfix enc: vorangestellt und ein Doppelpunkt (:) nachgestellt werden. Orts-IDs muss place_id: vorangestellt sein. Die Orts-ID kann nur angegeben werden, wenn die Anforderung einen API-Schlüssel oder eine Google Maps APIs Premium Plan-Client-ID enthält. Wegpunkte werden nur für Wegbeschreibungen für Kraftfahrzeuge, Fußgänger und Radfahrer unterstützt. Weitere Informationen zu Wegpunkten finden Sie weiter unten im Leitfaden zu Wegpunkten.
  • alternatives — ist dieser Wert auf true festgelegt, so kann der Directions-Dienst in der Antwort mehr als eine Streckenalternative ausgeben. Beachten Sie jedoch, dass die Angabe von Alternativen die Antwortzeit des Servers verlängern kann.
  • avoid — gibt an, dass die berechnete Route die genannten Argumente meiden soll. Dieser Parameter unterstützt die folgenden Argumente:
    • tolls gibt an, dass die berechnete Route mautpflichtige Straßen/Brücken meiden soll.
    • highways gibt an, dass die berechnete Route Autobahnen/Hauptverkehrsstraßen meiden soll.
    • ferries gibt an, dass die berechnete Route Fähren meiden soll.
    • indoor: Gibt an, dass die für Fußgänger oder öffentliche Verkehrsmittel berechnete Route Innenräume meiden soll. Nur Anforderungen mit einem API-Schlüssel oder einer Google Maps APIs Premium Plan-Client-ID enthalten standardmäßig Innenräume.
    Weitere Informationen finden Sie unten im Abschnitt Routenbeschränkungen.
  • language — die Sprache, in der die Ergebnisse zurückgegeben werden sollen.
    • Weitere Informationen finden Sie in der Liste der unterstützten Sprachen. Google aktualisiert die unterstützten Sprachen häufig. Die Liste ist daher unter Umständen nicht vollständig.
    • Wurde language nicht angegeben, versucht die API, die im Header Accept-Language angegebene bevorzugte Sprache oder die native Sprache der Domäne, aus der die Anforderung gesendet wurde, zu verwenden.
    • Die API versucht möglichst eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Um dieses Ziel zu erreichen, werden Adressen in der Landessprache zurückgegeben und bei Bedarf unter Berücksichtigung der bevorzugten Sprache in eine für den Nutzer lesbare Schrift umcodiert. Alle übrigen Adressen werden in der bevorzugten Sprache zurückgegeben. Alle Adresskomponenten werden in derselben Sprache zurückgegeben, die aus der ersten Komponente gewählt wird.
    • Wenn der Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die am besten passende Entsprechung.
    • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die die API zurückgibt, sowie auf die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen unterschiedlich je nach Sprache. Dies betrifft beispielsweise Abkürzungen für Straßentypen oder Synonyme, die möglicherweise in einer Sprache gültig sind, in einer anderen aber nicht. Beispielsweise sind utca und tér Synonyme für den Begriff Straße auf Ungarisch.
  • units — gibt an, welches Einheitensystem für die Anzeige der Ergebnisse verwendet werden soll. Die gültigen Werte sind unten im Abschnitt Einheitensysteme angegeben.
  • region — gibt den Regionscode als zweistelligen Ländercode der Top-Level-Domain (ccTLD) an. Weitere Informationen finden Sie unter Anforderung mit Regionsangabe.
  • arrival_time – gibt die gewünschte Ankunftszeit für Wegbeschreibungen für öffentliche Verkehrsmittel in Sekunden an (ab Mitternacht des 01.01.1970 UTC). Es kann entweder departure_time oder arrival_time angegeben werden, jedoch nicht beides. Beachten Sie, dass arrival_time als ganze Zahl angegeben werden muss.
  • departure_time — gibt die gewünschte Abreisezeit an. Die Zeit kann als ganze Zahl in Sekunden ab Mitternacht des 01.01.1970 UTC angegeben werden. Alternativ können Sie den Wert now verwenden, der die Abreisezeit auf den aktuellen Zeitpunkt (die nächste Sekunde) festlegt. Die Abreisezeit kann in zwei Fällen angegeben werden:
    • Für Anforderungen mit öffentlichen Verkehrsmitteln als Transportmittel: Es kann optional entweder departure_time oder arrival_time angegeben werden. Wird keine bestimmte Zeit angegeben, so wird für departure_time „jetzt“ verwendet.
    • Für Anforderungen mit Kraftfahrzeugen als Transportmittel: Geben Sie einen Wert für departure_time an, um eine Route und eine Reisezeit zu erhalten, bei der die Verkehrsbedingungen berücksichtigt werden (Antwortfeld: duration_in_traffic). Diese Option steht nur zur Verfügung, wenn die Anforderung einen gültigen API-Schlüssel oder eine gültige Google Maps APIs Premium Plan-Client-ID und -Signatur enthält. Die departure_time muss als der gegenwärtige oder ein zukünftiger Zeitpunkt festgelegt sein. Der Wert kann nicht in der Vergangenheit liegen.
  • traffic_model (Standard: best_guess) — gibt an, welche Annahmen bei der Berechnung der Reisedauer zugrunde gelegt werden sollen. Diese Einstellung beeinflusst den im Feld duration_in_traffic zurückgegebenen Wert. Er enthält die voraussichtliche Reisedauer basierend auf zurückliegenden Durchschnittswerten. Der Parameter traffic_model kann für Webbeschreibungen nur angegeben werden, wenn die Anforderung einen Wert für (departure_time) umfasst und einen API-Schlüssel oder eine Google Maps APIs Premium Plan-Client-ID enthält. Verfügbare Werte für diesen Parameter sind:
    • best_guess (Standard) gibt an, dass der für duration_in_traffic zurückgegebene Wert die bestmögliche Einschätzung der Verkehrsbedingungen auf der Grundlage von Werten aus Vergangenheit und Gegenwart darstellen soll. Dabei werden Werte aus der Gegenwart stärker berücksichtigt, je näher departure_time am Zeitpunkt „jetzt“ liegt.
    • pessimistic gibt an, dass der für duration_in_traffic zurückgegebene Wert höher als die tatsächliche Reisezeit an den meisten Tagen sein soll. Einzelne Tage mit besonders schlechten Verkehrsbedingungen können diesen Wert überschreiten.
    • optimistic gibt an, dass der für duration_in_traffic zurückgegebene Wert niedriger als die tatsächliche Reisezeit an den meisten Tagen sein soll. Einzelne Tage mit besonders guten Verkehrsbedingungen können diesen Wert unterschreiten.
    Mit dem Standardwert von best_guess werden die nützlichsten Vorhersagen für den größten Teil der Anwendungsfälle angegeben. Aufgrund der Art und Weise, wie Live-Verkehrsinformationen im Vorhersagemodell best_guess integriert werden, ist die mit best_guess vorhergesagte Reisezeit möglicherweise kürzer als die mit optimistic oder pessimistic angegebene Reisezeit.
  • transit_mode — gibt ein oder mehrere bevorzugte öffentliche Verkehrsmittel an. Dieser Parameter kann nur für öffentliche Verkehrsmittel angegeben werden, und nur, wenn die Anforderung einen API-Schlüssel oder eine Google Maps APIs Premium Plan-Client-ID enthält. Dieser Parameter unterstützt die folgenden Argumente:
    • bus gibt an, dass für die berechnete Route Busse bevorzugt werden sollen.
    • subway gibt an, dass für die berechnete Route die U-Bahn bevorzugt werden soll.
    • train gibt an, dass für die berechnete Route Züge bevorzugt werden sollen.
    • tram gibt an, dass für die berechnete Route Straßenbahnen und Stadtbahnen bevorzugt werden sollen.
    • rail gibt an, dass für die berechnete Route Züge, Straßenbahnen, Stadtbahnen und U-Bahnen bevorzugt werden sollen. Dies entspricht transit_mode=train|tram|subway.
  • transit_routing_preference — gibt Präferenzen für Routen mit öffentlichen Verkehrsmitteln an. Mit diesem Parameter können Sie die zurückgegebenen Optionen beeinflussen, anstatt die von der API standardmäßig ausgegebene beste Strecke übernehmen zu müssen. Dieser Parameter kann nur für öffentliche Verkehrsmittel angegeben werden, und nur, wenn die Anforderung einen API-Schlüssel oder eine Google Maps APIs Premium Plan-Client-ID enthält. Dieser Parameter unterstützt die folgenden Argumente:
    • less_walking gibt an, dass die Route möglichst wenige Abschnitte einbeziehen soll, die zu Fuß zurückgelegt werden müssen.
    • fewer_transfers gibt an, dass die Route eine möglichst geringe Anzahl von Umstiegen enthalten soll.

Beispiele für Anforderungen in Directions

Im folgenden Anforderungsbeispiel werden Wegbeschreibungen von Toronto, Ontario, nach Montreal, Quebec, zurückgegeben.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

Durch Ändern der Parameter mode und avoid kann die ursprüngliche Anforderung so umgewandelt werden, dass eine Wegbeschreibung für Radfahrer entlang einer malerischen Strecke ohne Hauptverkehrsstraßen zurückgegeben wird.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

Die nächste Anforderung sucht nach Wegbeschreibungen von Brooklyn, New York, nach Queens, New York. Da keine bestimmte Zeit angegeben wurde, wird als departure_time „jetzt“ verwendet.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

In der folgenden Anforderung ist eine bestimmte Abreisezeit enthalten.

Hinweis: In diesem Beispiel wurde als Abreisezeit 09:45 Uhr am 30. Juli 2012 angegeben. Um Fehler zu vermeiden, ändern Sie vor dem Einreichen der Anforderung den Parameter in einen Zeitpunkt in der Zukunft.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

Im folgenden Anforderungsbeispiel werden Orts-IDs verwendet, um Wegbeschreibungen von Glasgow, UK, nach Perth, UK, zurückzugeben.

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

Verkehrsmittel

Bei der Berechnung von Wegbeschreibungen können Sie mit mode das zu verwendende Verkehrsmittel angeben. Standardmäßig werden die Wegbeschreibungen für Kraftfahrzeuge (driving) berechnet. Folgende Verkehrsmittel werden unterstützt:

  • driving (Standardeinstellung): Wegbeschreibungen unter Verwendung des Straßennetzes.
  • walking: Wegbeschreibungen unter Verwendung von Fußwegen (sofern verfügar).
  • bicycling: Wegbeschreibungen unter Verwendung von Radwegen und bevorzugten Straßen (sofern verfügbar).
  • transit: Wegbeschreibungen unter Verwendung von öffentlichen Verkehrsmitteln (sofern verfügbar). Wenn Sie als Verkehrsmittel transit festlegen, können Sie optional eine Abreisezeit (departure_time) oder eine Ankunftszeit (arrival_time) angeben. Wird keine bestimmte Zeit angegeben, so wird für departure_time „jetzt“ verwendet. Optional können Sie außerdem die Art des öffentlichen Verkehrsmittels mit transit_mode und/oder eine Streckenpräferenz mit transit_routing_preference angeben.

Hinweis: Wegbeschreibungen für Fußgänger und Radfahrer umfassen gegebenenfalls auch andere Wege als Fuß- und Radwege und geben in diesem Fall Warnungen (warnings) zurück, die Sie dem Benutzer anzeigen müssen.

Wegpunkte

Bei der Berechnung von Routen mit der Google Maps Directions API können Sie für Wegbeschreibungen für Kraftfahrzeuge, Fußgänger oder Radfahrer auch Wegpunkte angeben. Wegpunkte werden für Wegbeschreibungen für öffentliche Verkehrsmittel nicht unterstützt. Mithilfe von Wegpunkten können zusätzliche Orte in die Berechnung von Routen aufgenommen werden. Die zurückgegebene Route enthält Aufenthalte an den angegebenen Wegpunkten.

Geben Sie die Wegpunkte im Parameter waypoints an.

  • Sie können einen oder mehrere Orte getrennt durch einen senkrechten Strich (|) in Form einer Adresse, als Längen- oder Breitengradkoordinaten oder als Orts-ID angeben.
    • Wenn Sie eine Adresse als Zeichenfolge übergeben, geocodiert der Directions-Dienst die Zeichenfolge und wandelt sie in Längengrad- und Breitengradkoordinaten um, um so die Wegbeschreibungen zu berechnen. Diese Koordinate kann sich von der Koordinate unterscheiden, die durch die Google Maps Geocoding API zurückgegeben wird. Sie kann bspw. einen Gebäudeeingang anstelle der Gebäudemitte bezeichnen.
    • Wenn Sie Koordinaten (Längen- und Breitengrad) übergeben, werden diese unverändert verwendet. Beachten Sie, dass sich zwischen den Werten für den Längen- und den Breitengrad kein Leerzeichen befinden darf.
    • Wenn Sie eine Orts-ID übergeben, müssen Sie dieser das Präfix place_id: voranstellen. Eine Orts-ID können Sie nur übergeben, wenn die Anforderung einen API-Schlüssel oder eine Google Maps APIs Premium Plan-Client-ID enthält. Sie können Orts-IDs mithilfe der Google Maps Geocoding API und der Google Places API (einschließlich automatischer Vervollständigung von Orten) abrufen. Ein Beispiel, in dem Orts-IDs aus der Autovervollständigung von Orten verwendet werden, finden Sie unter Autovervollständigung von Orten und Wegbeschreibungen. Weitere Informationen zu Orts-IDs finden Sie unter Orts-IDs – Übersicht.
  • Alternativ können Sie einen codierten Satz von Koordinaten über den Algorithmus für codierte Polylinien übergeben. Dies ist insbesondere nützlich, wenn Sie eine große Anzahl von Wegpunkten haben, da die URL erheblich kürzer ist, wenn eine codierte Polylinie verwendet wird.
    • Codierten Polylinien muss das Präfix enc: vorangestellt und ein Doppelpunkt (:) nachgestellt werden. Beispiel: waypoints=enc:gfo}EtohhU:
    • Sie können auch mehrere codierte Polylinien einfügen, die durch einen senkrechten Strich (|) voneinander getrennt sind. Beispiel: waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|via:enc:udymA{~bxM:

Die folgende URL initiiert eine Directions-Anforderung nach einer Route von Boston, MA, nach Concord, MA, mit Aufenthalten in Charlestown und Lexington:

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&key=YOUR_API_KEY

Für jeden Wegpunkt der Anforderung enthält die Antwort einen zusätzlichen Eintrag im Array legs, der die Einzelheiten dieses Reiseabschnitts angibt.

Wenn für die Route Wegpunkte ohne Aufenthalt verwendet werden sollen, stellen Sie dem Wegpunkt via: voran. Durch Wegpunkte mit dem Präfix via: wird kein Eintrag im Array legs hinzugefügt. Stattdessen wird die Strecke durch den angegebenen Wegpunkt geführt.

Die folgende URL ändert die vorherige Anforderung, sodass die Reise ohne Aufenthalt über Lexington geführt wird.

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|via:Lexington,MA&key=YOUR_API_KEY

Das Präfix via: eignet sich besonders für die Erstellung von Routen mit Wegpunkten, die der Benutzer durch Ziehen auf der Karte bestimmt hat. Dadurch erfährt der Benutzer in Echtzeit, wie die gewählte Strecke aussehen wird. Außerdem wird sichergestellt, dass die Wegpunkte sich an für die Google Maps Directions API zugänglichen Orten befinden.

Über die folgende URL werden Wegpunkte mithilfe von Koordinaten (Längen- und Breitengrad) angefordert:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:-37.81223%2C144.96254%7Cvia:-34.92788%2C138.60008&key=YOUR_API_KEY

Dies ist dieselbe Anforderung, wobei in diesem Fall jedoch eine codierte Polylinie verwendet wird:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:enc:lexeF{~wsZejrPjtye@:&key=YOUR_API_KEY

Wegpunkte optimieren

Standardmäßig berechnet der Directions-Dienst die Strecke über die Wegpunkte in der angegebenen Reihenfolge. Um die Wegpunkte effizienter anzuordnen und die ausgegebene Route zu optimieren, können Sie als erstes Argument im Parameter waypoints optimize:true übergeben. (Diese Optimierung ist eine Anwendung des Problems des Handlungsreisenden.) Der optimierte primäre Faktor ist die Reisezeit, wobei aber bei der Entscheidung, welche Route die effizienteste ist, weitere Faktoren wie Entfernung, Anzahl der Abbiegevorgänge und vieles mehr berücksichtigt werden können. Um ihre Route zu optimieren, müssen alle Wegpunkte für den Directions-Dienst als Aufenthalte definiert sein.

Wenn Sie den Directions-Dienst anweisen, die Reihenfolge der Wegpunkte zu optimieren, wird diese Reihenfolge im Feld waypoint_order im Objekt routes zurückgegeben. Das Feld waypoint_order gibt nullbasierte Werte zurück.

Im folgenden Beispiel wird mithilfe der Streckenoptimierung eine Route von Adelaide, South Australia, in alle wichtigen Weinregionen von South Australia berechnet.

https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide,SA&destination=Adelaide,SA&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA&key=YOUR_API_KEY

Eine Überprüfung der Route zeigt, dass sie mit folgender Wegpunkt-Reihenfolge berechnet wurde:

"waypoint_order": [ 1, 0, 2, 3 ]

Einschränkungen

Wegbeschreibungen können unter Berücksichtigung bestimmter Einschränkungen berechnet werden. Einschränkungen werden durch den Parameter avoid und ein zugehöriges Argument bestimmt, das die zu vermeidende Einschränkung angibt. Folgende Einschränkungen werden unterstützt:

  • avoid=tolls
  • avoid=highways
  • avoid=ferries

Um eine Strecke anzufordern, die sowohl mautpflichtige Abschnitte als auch Autobahnen und Fähren umgeht, können diese Einschränkungen zusammen an den Parameter „avoid“ übergeben werden. Beispiel: avoid=tolls|highways|ferries.

Hinweis: Durch Addieren von Einschränkungen werden Routen mit der zu vermeidenden Eigenschaft nicht ausgeschlossen, sondern lediglich günstigere Routen als Ergebnis bevorzugt.

Einheitensysteme

Die Länge eines bestimmten Streckenabschnitts kann dem Benutzer in den Ergebnissen von Directions-Anforderungen durch text in den Feldern distance angezeigt werden. Standardmäßig verwendet dieser Text das im Land des Ausgangsorts gültige Einheitensystem.

So wird die Länge der Strecke von Chicago, IL, nach Toronto, ONT, in Meilen, die Länge der umgekehrten Strecke jedoch in Kilometern angezeigt. Sie können dieses Einheitensystem außer Kraft setzen, indem Sie im Parameter units der Anforderung explizit ein bestimmtes System festlegen. Übergeben Sie dazu einen der folgenden Werte:

  • metric: Das metrische System wird verwendet. Entfernungen werden in Kilometern und Metern angegeben.
  • imperial: Das angloamerikanische System wird verwendet. Entfernungen werden in Meilen und Fuß angegeben.

Hinweis: Diese Einstellung beeinflusst nur den in den Feldern distance angezeigten text. In den Feldern distance sind zudem Werte (values) enthalten, die stets in Metern angegeben werden.

Anforderung mit Regionsangabe

Verwenden Sie den Parameter region, um den Directions-Dienst auf eine bestimmte Region ausgerichtete Ergebnisse zurückgeben zu lassen. Dazu verwendet dieser Parameter ein ccTLD-Argument (Ländercode der Top-Level-Domain). Die meisten ccTLD-Codes stimmen mit den ISO 3166-1-Codes überein, wobei es einige Ausnahmen gibt. Der ccTLD von Großbritannien lautet „uk“ (.co.uk), der ISO 3166-1-Code jedoch „gb“ (für „Vereinigtes Königreich Großbritannien und Nordirland“).

Sie können alle Domänen verwenden, für die die Anwendung Google Maps Wegbeschreibungen bereitstellt.

Beispiel: Eine Anforderung von „Toledo“ nach „Madrid“ gibt ein Ergebnis zurück, wenn region auf es festgelegt ist, da Toledo dann als Stadt in Spanien interpretiert wird:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

Dieselbe Anforderung ohne den Parameter region gibt keine Ergebnisse zurück, da Toledo hier als Stadt in Ohio interpretiert wird:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

Antworten in Directions

Antworten in Directions werden in dem Format zurückgegeben, das im Flag output im URL-Pfad der Anforderung angegeben wurde.

Beispielantworten

Im Folgenden sehen Sie eine HTTP-Anforderung für die Route von Chicago, IL, nach Los Angeles, CA, über zwei Wegpunkte in Joplin, MO, und Oklahoma City, OK.

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

Im obenstehenden Beispiel wird die Ausgabe in JSON angefordert. Sie kann jedoch auch in XML angefordert werden. Klicken Sie unten auf die jeweilige Registerkarte, um sich die Beispielantworten in JSON und XML anzusehen.

Da Directions-Antworten oft sehr umfangreich sind, wurden in diesem Beispiel mehrfach auftretende Elemente weggelassen.

JSON
{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

Normalerweise wird im Array routes nur ein Eintrag zurückgegeben. Um mehrere Routen zu erhalten, übergeben Sie alternatives=true.

Wenn Sie aus diesen Ergebnissen Werte extrahieren möchten, müssen Sie sie parsen. Das Parsen von JSON ist relativ einfach. Unter JSON parsen finden Sie einige empfohlene Entwurfsmuster.

XML
<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

Die XML-Antwort besteht aus einer einzelnen <DirectionsResponse> und den folgenden Elementen der obersten Ebene:

  • <status> enthält Metadaten zur Anforderung. Weitere Informationen finden Sie weiter unten unter Statuscodes.
  • Ein <geocoded_waypoint> pro Wegpunkt, Ausgangsort, Zielort und Einzelheiten zu den Ergebnissen der Geocodierung dieser Orte. Auch leere Elemente vom Typ <geocoded_waypoint/> sind möglich. Weitere Informationen finden Sie unten im Abschnitt Geocodierte Wegpunkte.
  • Null oder mehrere Elemente vom Typ <route>, jedes mit einem Satz an Streckeninformationen zwischen Ausgangs- und Zielort.

Sie sollten json als das bevorzugte Ausgabe-Flag verwenden, sofern Ihr Dienst nicht aus irgendeinem Grund xml verlangt. Die Verarbeitung von XML-Strukturen erfordert einige Sorgfalt. Knoten und Elemente müssen präzise referenziert werden. Unter XML mit XPath parsen finden Sie einige empfohlene Entwurfsmuster für die Ausgabeverarbeitung.

Im verbleibenden Teil dieser Dokumentation wird JSON-Syntax verwendet. In den meisten Fällen ist das Ausgabeformat für die Darstellung von Konzepten oder Feldnamen in der Dokumentation nicht ausschlaggebend. Beachten Sie jedoch die folgenden Unterschiede:

  • XML-Ergebnisse sind von dem Stammelement <DirectionsResponse> umschlossen.
  • JSON gibt Einträge mit mehreren Elementen durch Pluralarrays (z. B. steps und legs) an, während XML dafür mehrere einzelne Elemente (z. B. <step> und <leg>) verwendet.
  • JSON gibt die Wegpunkt-Reihenfolge über das Feld waypoint_order an, während XML diese über einzelne Elemente vom Typ <waypoint_index> angibt.
  • Leere Elemente werden in JSON durch leere Arrays angegeben, in XML dagegen durch keines dieser Elemente. Antworten, die keine Ergebnisse generieren, geben in JSON das leere Array routes zurück, in XML jedoch keine <route>-Elemente.

Antwortelemente in Directions

Antworten in Directions enthalten die folgenden Stammelemente:

  • status enthält Metadaten zur Anforderung. Weitere Informationen finden Sie weiter unten unter Statuscodes.
  • geocoded_waypoints enthalten ein Array mit Einzelheiten zur Geocodierung von Ausgangsort, Zielort und Wegpunkten. Weitere Informationen finden Sie unten im Abschnitt Geocodierte Wegpunkte.
  • routes enthält ein Array mit Routen vom Ausgangs- zum Zielort. Weitere Informationen finden Sie unten im Abschnitt Routen. Routen bestehen aus geschachtelten Abschnitten (legs) und Schritten (steps).
  • available_travel_modes enthält ein Array mit verfügbaren Verkehrsmitteln. Dieses Feld wird zurückgegeben, wenn in einer Anforderung ein Verkehrsmittel (mode) angegeben wird und keine Ergebnisse zurückgegeben werden. Das Array enthält die verfügbaren Verkehrsmittel in den Ländern der vorgegebenen Gruppe von Wegpunkten. Dieses Feld wird nicht zurückgegeben, wenn es sich bei einem oder mehreren der Wegpunkte um Wegpunkte vom Typ via: handelt. Weitere Informationen finden Sie weiter unten.

Statuscodes

Das Feld status im Directions-Antwortobjekt enthält den Status der Anforderung und kann auch Debuginformationen enthalten, die Ihnen helfen sollen, herauszufinden, warum die Anforderung im Directions-Dienst nicht erfolgreich war. Das Feld status kann folgende Werte enthalten:

  • OK gibt an, dass die Antwort ein gültiges Ergebnis (result) enthält.
  • NOT_FOUND gibt an, dass mindestens einer der Orte, die in der Anforderung als Ausgangsort, Zielort oder Wegpunkt angegeben wurden, nicht geocodiert werden konnte.
  • ZERO_RESULTS gibt an, dass zwischen Start- und Zielort keine Route ermittelt werden konnte.
  • MAX_WAYPOINTS_EXCEEDED gibt an, dass in der Anforderung zu viele Wegpunkte (waypoints) vorgegeben wurden. Für Anwendungen, die die Google Maps Directions API als Webdienst oder den Directions-Dienst in der Google Maps JavaScript API verwenden, ist die maximal zulässige Anzahl der Wegpunkte (waypoints) 23 (plus Start und Ziel). Google Maps APIs Premium Plan-Kunden können Anforderungen mit bis zu 23 Wegpunkten übermitteln (plus Start und Ziel).
  • INVALID_REQUEST gibt an, dass die Anforderung ungültig war. Häufige Ursachen sind ungültige Parameter oder Parameterwerte.
  • OVER_QUERY_LIMIT gibt an, dass der Dienst in einem bestimmten Zeitraum zu viele Anforderungen von Ihrer Anwendung erhalten hat.
  • REQUEST_DENIED gibt an, dass die Verwendung des Directions-Dienstes durch Ihre Anwendung verweigert wurde.
  • UNKNOWN_ERROR gibt an, dass eine Anforderung aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Möglicherweise ist die Anforderung beim nächsten Versuch erfolgreich.

Fehlermeldungen

Wird ein anderer Statuscode als OK zurückgegeben, so wird im Directions-Antwortobjekt ggf. das zusätzliche Feld error_message angezeigt. Dieses Feld enthält weitere detaillierte Informationen zu den Gründen für den zurückgegebenen Statuscode.

Hinweis: Dieses Feld wird nicht immer angezeigt, und sein Inhalt unterliegt Änderungen.

Geocodierte Wegpunkte

Einzelheiten zur Geocodierung der Wegpunkte und von Ausgangs- und Zielort finden sich im Array geocoded_waypoints (JSON). Damit lässt sich ermitteln, weshalb der Dienst unerwartete oder keine Routen zurückgegeben hat.

Die Elemente im Array geocoded_waypoints entsprechen gemäß ihrer nullbasierten Position dem Ausgangsort, den Wegpunkten in der angegebenen Reihenfolge und dem Zielort. Jedes Element enthält die folgenden Einzelheiten zur Geocodierung des jeweiligen Wegpunkts:

  • geocoder_status gibt den Statuscode des Vorgangs an. Dieses Feld kann folgende Werte enthalten:
      
    • "OK" gibt an, dass keine Fehler aufgetreten sind. Die Adresse wurde erfolgreich geparst, und es wurde mindestens ein Geocode zurückgegeben.
    • "ZERO_RESULTS" gibt an, dass das Geocoding erfolgreich war, aber keine Ergebnisse zurückgegeben hat. Dies kann eintreten, wenn dem Geocoder eine nicht existierende Adresse (address) übergeben wurde.
  • 

    partial_match gibt an, dass der Geocoder kein genaues Ergebnis für die Anforderung zurückgegeben hat, jedoch eine Übereinstimmung mit einem Teil der angeforderten Adresse gefunden hat. Überprüfen Sie ggf. die Anforderung auf Tippfehler und/oder Unvollständigkeit.

    Teilübereinstimmungen treten am häufigsten bei Anschriften auf, die an dem von Ihnen in der Anforderung übergebenen Ort nicht existieren. Teilübereinstimmungen können auch zurückgegeben werden, wenn eine Anforderung mit mehr als einem Standort am selben Ort übereinstimmt. So wird für „21 Henr St, Bristol, UK“ eine Teilübereinstimmung für Henry Street und Henrietta Street zurückgegeben. Enthält eine Anforderung einen Adressbestandteil mit Tippfehlern, schlägt der Geocoder möglicherweise eine andere Adresse vor. Auf diese Weise ausgelöste Vorschläge werden ebenfalls als Teilübereinstimmung gekennzeichnet.

  • place_id ist ein eindeutiger Bezeichner, der für andere Google APIs verwendet werden kann. Beispielsweise können Sie die Orts-ID (place_id) aus einer Google Place Autocomplete-Antwort verwenden, um Wegbeschreibungen zu lokalen Unternehmen zu berechnen. Weitere Informationen finden Sie unter Orts-IDs – Übersicht.
  • types gibt den Adresstyp (address type) des Ergebnisses der Geocodierung an, das für die Berechnung verwendet wurde. Folgende Adresstypen werden zurückgegeben: 
    • street_address bezeichnet eine genaue Anschrift.
    • route bezeichnet eine Straße mit einem Namen oder einer Nummer (z. B. „US 101“).
    • intersection bezeichnet eine wichtige Kreuzung, meist zweier Hauptstraßen.
    • political bezeichnet eine Verwaltungseinheit. Dieser Typ steht meist für ein Polygon einer öffentlichen Einrichtung.
    • country bezeichnet eine nationale Verwaltungseinheit und ist normalerweise der höchste Typ in der vom Geocoder zurückgegebenen Reihenfolge.
    • administrative_area_level_1 bezeichnet eine Verwaltungseinheit erster Ordnung unterhalb der Stufe „Land“. In den USA sind diese Verwaltungsebenen die Bundesstaaten. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern. In den meisten Fällen sind Kurzbezeichnungen vom Typ administrative_area_level_1 eng an die Untereinheiten des Standards ISO 3166-2 und andere weit verbreitete Listen angelehnt. Eine Garantie hierfür können wir jedoch nicht geben, da unsere Geocoding-Ergebnisse auf verschiedenen Signalen und Standortdaten basieren.
    • administrative_area_level_2 bezeichnet eine Verwaltungseinheit zweiter Ordnung unterhalb der Stufe „Land“. In den USA sind diese Verwaltungsebenen die Countys. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
    • administrative_area_level_3 bezeichnet eine Verwaltungseinheit dritter Ordnung unterhalb der Stufe „Land“. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
    • administrative_area_level_4 bezeichnet eine Verwaltungseinheit vierter Ordnung unterhalb der Stufe „Land“. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
    • administrative_area_level_5 bezeichnet eine Verwaltungseinheit fünfter Ordnung unterhalb der Stufe „Land“. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
    • colloquial_area bezeichnet eine allgemein verwendete Alternativbezeichnung der Einheit.
    • locality bezeichnet die Verwaltungseinheit einer Stadt mit Selbstverwaltung.
    • ward bezeichnet eine bestimmte Art von Ort in Japan (Stadtbezirk) und wird zur Unterscheidung zwischen den Bestandteilen japanischer Adressen verwendet.
    • sublocality bezeichnet eine Verwaltungseinheit erster Ordnung unterhalb der Stufe „Stadt“. Einigen Orten kann zusätzlich einer der folgenden Typen zugewiesen werden: sublocality_level_1 bis sublocality_level_5. Jede dieser Ebenen ist eine Verwaltungseinheit. Je höher die Zahl, desto kleiner das geografische Gebiet.
    • neighborhood bezeichnet ein bestimmtes Viertel.
    • premise bezeichnet meist ein bestimmtes Gebäude oder eine Gebäudegruppe mit einer gemeinsamen Bezeichnung.
    • subpremise bezeichnet eine Einheit erster Ordnung unterhalb einer Gebäudegruppe, meist ein einzelnes Gebäude in einer Gebäudegruppe mit einer gemeinsamen Bezeichnung.
    • postal_code bezeichnet die Postleitzahl, die zur Adressierung von Post innerhalb eines Landes verwendet wird.
    • natural_feature bezeichnet ein landschaftliches Wahrzeichen.
    • airport bezeichnet einen Flughafen.
    • park bezeichnet einen bestimmten Park.
    • point_of_interest bezeichnet einen bestimmten Point of Interest (POI). Dazu gehören bedeutende lokale Objekte, die sich keiner anderen Kategorie zuordnen lassen, wie z. B. „Empire State Building“ oder „Freiheitsstatue“.

    Eine leere Typenliste bedeutet, dass für einen bestimmten Adressbestandteil keine Typen vorhanden sind, wie z. B. im Falle des französischen Lieu-dit.

Gibt der Dienst für Wegpunkte, die als Textwerte mit Längen- und Breitengrad angegeben wurden, keine Ergebnisse zurück, so werden diese Einzelheiten nicht angezeigt. Der Grund dafür ist, dass Wegpunkte nur dann umgekehrt geocodiert werden und ihre Adresse ermittelt wird, wenn eine Route gefunden wurde. Im Array geocoded_waypoints sind die jeweiligen Orte durch ein leeres JSON-Objekt besetzt.

Routen

Gibt die Google Maps Directions API Ergebnisse zurück, so werden diese in das JSON-Array routes platziert. Auch wenn der Dienst keine Ergebnisse zurückgibt (z. B. wenn Ausgangs- und/oder Zielort nicht existieren), gibt er dennoch ein leeres routes-Array zurück. (XML-Antworten bestehen dagegen aus keinem oder mehreren <route>-Elementen.)

Jedes Element des Array routes enthält ein einziges Ergebnis für den angegebenen Ausgangs- und Zielort. Diese Route kann je nachdem, ob Wegpunkte angegeben wurden, aus einem oder mehreren legs bestehen. Darüber hinaus enthält die Route Copyright- und Warnhinweise, die dem Benutzer zusätzlich zu den Routeninformationen angezeigt werden müssen.

Jede Route im Feld routes kann die folgenden Felder enthalten:

  • summary enthält einen kurzen, beschreibenden Text der Route, der eine Benennung und Unterscheidung dieser von Alternativrouten ermöglicht.
  • legs[] enthält ein Array mit Informationen über einen Abschnitt zwischen zwei Orten der Route. Für jeden Wegpunkt oder Zielort wird ein gesonderter Abschnitt angegeben. Routen ohne Wegpunkte enthalten im Array legs genau einen Abschnitt. Jeder Abschnitt besteht aus einer Reihe von steps. Weitere Informationen finden Sie unten im Abschnitt Abschnitte in Directions
  • waypoint_order (oder <waypoint_index> in XML) enthält ein Array, das die Reihenfolge der Wegpunkte in der berechneten Route angibt. Die Reihenfolge der Wegpunkte kann geändert werden, wenn im Parameter waypoints der Anforderung optimize:true übergeben wurde.
  • overview_polyline enthält ein einzelnes Objekt points, das eine codierte Polyliniendarstellung der Route umfasst. Die Polylinie ist der annähernde (geglättete) Pfad der ermittelten Wegbeschreibung.
  • bounds enthält den Begrenzungsrahmen des Anzeigebereichs der overview_polyline.
  • copyrights enthält die für diese Route anzuzeigenden Copyright-Hinweise. Diese Informationen müssen Sie selbst bearbeiten und anzeigen.
  • warnings[] enthält ein Array mit Warnungen, die für diese Wegbeschreibung angezeigt werden müssen. Diese Warnungen müssen Sie selbst bearbeiten und anzeigen.
  • fare: Enthält den Gesamtbetrag der Tickets auf dieser Strecke. Diese Eigenschaft wird nur bei Anforderungen für öffentliche Verkehrsmittel und Routen zurückgegeben, auf denen Tarifinformationen für sämtliche Abschnitte verfügbar sind. Folgende Informationen werden ausgegeben:
    • currency: Der Währungscode nach ISO 4217 gibt die Währung des Betrags an.
    • value: Der Gesamtbetrag in der oben angegebenen Währung.
    • text: Der Gesamtbetrag im Format der angeforderten Sprache.

Im Folgenden finden Sie ein Beispiel für Tarifinformationen auf einer Route:

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

Abschnitte

Jedes Element im Array legs gibt einen einzelnen Abschnitt der Route zwischen Ausgangs- und Zielort an. Routen, die keine Wegpunkte enthalten, bestehen aus einem einzigen „Abschnitt“, Routen mit einem oder mehreren Wegpunkten aus mehreren Abschnitten.

Jeder Abschnitt im Feld/in den Feldern legs kann die folgenden Felder enthalten:

  • steps[] enthält ein Array aus Schritten (steps) mit Informationen zu jedem einzelnen Schritt im Abschnitt einer Reise. Weitere Informationen finden Sie unten im Abschnitt Schritte in Directions.
  • distance gibt die Entfernung an, die auf einem bestimmten Abschnitt zurückgelegt wird. Das Feld besteht aus folgenden Elementen:

    • Mit value wird die Entfernung in Metern angegeben.
    • text enthält eine lesbare Darstellung der Entfernung in der Einheit des Ausgangsorts (oder der Einheit, mit der der Parameter units in der Anforderung überschrieben wurde). So wird bei Ausgangsorten in den USA die Entfernung stets in Meilen und Fuß angegeben. Beachten Sie, dass der Wert im Feld distance.value stets in Metern ausgedrückt wird, unabhängig davon, welches Einheitensystem für den Text verwendet wird.

    Diese Felder sind möglicherweise nicht vorhanden, wenn die Entfernung nicht bekannt ist.

  • duration gibt die Gesamtdauer des Abschnitts als Feld mit folgenden Elementen an:

    • value gibt die Dauer in Sekunden an.
    • text enthält eine menschenlesbare Darstellung der Dauer.

    Diese Felder sind möglicherweise nicht vorhanden, wenn die Dauer nicht bekannt ist.

  • duration_in_traffic gibt die Gesamtdauer dieses Abschnitts an. Dieser Wert ist eine Schätzung der Dauer auf der Grundlage gegenwärtiger und zurückliegender Verkehrsbedingungen. Im Parameter traffic_model finden Sie die Optionen, mit denen Sie eine optimistische, pessimistische oder bestmögliche Schätzung anfordern können. Die Dauer wird nur dann zurückgegeben, wenn alle der folgenden Bedingungen erfüllt sind:

    • Die Anforderung enthält einen gültigen API-Schlüssel oder eine gültige Google Maps APIs Premium Plan-Client-ID und Signatur.
    • Die Anforderung enthält keine Wegpunkte mit Aufenthalt. Wenn die Anforderung Wegpunkte enthält, muss diesen das Präfix via: vorangestellt werden, um Aufenthalte zu vermeiden.
    • Die Anforderung bezieht sich auf eine Wegbeschreibung für Kraftfahrzeuge – der Parameter mode ist auf driving festgelegt.
    • Die Anforderung enthält den Parameter departure_time.
    • Für die angeforderte Route sind Informationen über die Verkehrsbedingungen 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 geschätzte Ankunftszeit für diesen Abschnitt. Diese Eigenschaft wird nur bei Anforderungen für öffentliche Verkehrsmittel zurückgegeben. Das Ergebnis wird als Objekt Time mit drei Eigenschaften zurückgegeben:
    • value: die Zeit definiert als JavaScript-Objekt Date.
    • text die Zeit definiert als Zeichenfolge. Die Zeit wird in der Zeitzone des Zielorts angegeben.
    • time_zone enthält die Zeitzone dieses Halts. Der Wert ist der Name der Zeitzone gemäß Definition der IANA-Zeitzonen-Datenbank, bspw. „America/New_York“.
  • departure_time enthält die geschätzte Abfahrtzeit für diesen Abschnitt und wird als Objekt Time angegeben. departure_time wird nur bei Anforderungen für öffentliche Verkehrsmittel zurückgegeben.
  • start_location enthält die Koordinaten (Längen- und Breitengrad) des Ausgangsorts dieses Abschnitts. Da die Directions API für die Berechnung von Wegbeschreibungen die dem Ausgangs- und Zielort nächstgelegene Reiseoption (normalerweise eine Straße) verwendet, kann sich start_location vom angegebenen Ausgangsort dieses Abschnitts unterscheiden, wenn sich bspw. die Straße nicht in dessen Nähe befindet.
  • end_location enthält die Koordinaten (Längen- und Breitengrad) des Zielorts dieses Abschnitts. Da die Google Maps Directions API für die Berechnung von Wegbeschreibungen die dem Ausgangs- und Zielort nächstgelegende Reiseoption (normalerweise eine Straße) verwendet, kann sich end_location vom angegebenen Zielort dieses Abschnitts unterscheiden, wenn sich bspw. die Straße nicht in dessen Nähe befindet.
  • start_address enthält die lesbare Adresse (normalerweise die genaue Anschrift) des Ausgangsorts und ist das Ergebnis der umgekehrten Geocodierung der start_location dieses Abschnitts.
  • end_address enthält die lesbare Adresse (normalerweise die genaue Anschrift) des Zielorts und ist das Ergebnis der umgekehrten Geocodierung der end_location dieses Abschnitts.

Schritte

Durch jedes Element im Array steps wird ein einzelner Schritt der berechneten Wegbeschreibung definiert. Ein Schritt ist die kleinste Einheit der Route und beschreibt eine einzelne, bestimmte Anweisung für die Reise. Beispiel: „An der W. 4th St. links abbiegen“ Außer der Anweisung enthält der Schritt auch Informationen zu Entfernung und Dauer dieses Schritts in Bezug auf den nächsten. Beispielsweise kann der Schritt „Fahren Sie auf die I-80 West“ die Entfernung „37 Meilen“ und die Dauer „40 Minuten“ enthalten und somit darauf hinweisen, dass der nächste Schritt 37 Meilen bzw. 40 Minuten von diesem entfernt ist.

Wird mit der Google Maps Directions API nach Wegbeschreibungen für öffentliche Verkehrsmittel gesucht, dann enthält das Array „Steps“ zusätzliche Angaben in Form des Arrays transit_details. Umfasst die Wegbeschreibung verschiedene Transportmittel, so werden die detaillierten Beschreibungen für Fußgänger oder Kraftfahrzeuge in dem inneren Array steps angegeben. Ein Schritt in der Wegbeschreibung für Fußgänger enthält bspw. Beschreibungen vom Ausgangs- zum Zielort: „Gehen Sie zur Innes Ave & Fitch St.“ Für diese Route enthält dieser Schritt detaillierte Wegbeschreibungen im inneren Array steps, wie z. B.: „Gehen Sie in Richtung Nordwesten“, „Biegen Sie links auf Arelious Walker ab“ und „Biegen Sie links auf Innes Ave ab“.

Jeder Schritt im Feld/in den Feldern steps kann die folgenden Felder enthalten:

  • html_instructions enthält Anweisungen für diesen Schritt, die als HTML-Zeichenfolge dargestellt werden.
  • distance enthält die bei diesem Schritt zurückgelegte Entfernung. (Weitere Informationen zu diesem Feld finden Sie oben im Abschnitt Abschnitte in Directions.) Dieses Feld ist möglicherweise nicht definiert, wenn die Entfernung nicht bekannt ist.
  • duration enthält die Zeit, die normalerweise für diesen Schritt benötigt wird. (Weitere Informationen zu diesem Feld finden Sie oben im Abschnitt Abschnitte in Directions.) Dieses Feld ist möglicherweise nicht definiert, wenn die Dauer nicht bekannt ist.
  • start_location enthält die Koordinaten des Ausgangspunkts dieses Schritts als einzelnen Satz mit den Feldern lat und lng.
  • end_location enthält die Koordinaten des Endpunkts dieses Schritts als einzelnen Satz mit den Feldern lat und lng.
  • polyline enthält ein einzelnes Objekt points, das eine codierte Polyliniendarstellung des Schritts umfasst. Die Polylinie ist der annähernde (geglättete) Pfad des Schritts.
  • steps enthält detaillierte Angaben für Fußgänger oder Kraftfahrzeuge in Wegbeschreibungen für öffentliche Verkehrsmittel. Diese Unterschritte sind nur verfügbar, wenn für travel_mode „transit“ festgelegt ist. Das innere Array steps ist vom selben Typ wie steps.
  • transit_details enthält Informationen zu öffentlichen Verkehrsmitteln. Dieses Feld wird nur zurückgegeben, wenn für travel_mode „transit“ festgelegt ist. Weitere Informationen finden Sie unten im Abschnitt Informationen zu öffentlichen Verkehrsmitteln.

Informationen zu öffentlichen Verkehrsmitteln

Wegbeschreibungen für öffentliche Verkehrsmittel geben zusätzliche Informationen zurück, die für andere Transportmittel nicht relevant sind. Diese zusätzlichen Eigenschaften werden durch das Objekt transit_details dargestellt, das als Feld eines Elements im Array steps[] zurückgegeben wird. Über das Objekt TransitDetails haben Sie Zugriff auf zusätzliche Informationen zu Haltestelle, Linie und Beförderungsunternehmen.

Das Objekt transit_details kann die folgenden Felder enthalten:

  • arrival_stop und departure_stop enthält Informationen über die Haltestellen dieses Teils der Reise. Dazu können folgende Angaben gehören:
    • name: der Name der Haltestelle, z. B. „Union Square“.
    • location: die Koordinaten der Haltestelle als Feld mit lat und lng.
  • arrival_time und departure_time: die Ankunfts- bzw. Abfahrtzeiten für diesen Abschnitt der Reise, angegeben durch die folgenden drei Eigenschaften:
    • text die Zeit definiert als Zeichenfolge. Die Zeit wird in der Zeitzone des Zielorts angegeben.
    • value: die Zeit als Unixzeit in Sekunden ab Mitternacht des 1. Januar 1970 UTC.
    • time_zone enthält die Zeitzone dieses Halts. Der Wert ist der Name der Zeitzone gemäß Definition der IANA-Zeitzonen-Datenbank, bspw. „America/New_York“.
  • headsign: die Fahrtrichtung der jeweiligen Linie, wie sie auf dem Fahrzeug oder an der Haltestelle angegeben ist. Oft ist dies der Name der Endhaltestelle.
  • headway: die erwartete Anzahl Sekunden zwischen Abfahrten von dieser Haltestelle zu dieser Zeit. Beträgt der Wert von headway bspw. 600, so sollte der nächste Bus in 10 Minuten abfahren.
  • num_stops enthält die Anzahl der Haltestellen in diesem Schritt, wobei die Ankunftshaltestelle mitgezählt wird, die Abfahrtshaltestelle jedoch nicht. Beginnt die Fahrt bspw. bei Abfahrtshaltestelle A, passiert dann die Haltestellen B und C und endet an Haltestelle D, so gibt num_stops den Wert 3 zurück.
  • line enthält Informationen zur jeweiligen Linie und kann die folgenden Eigenschaften umfassen:
    • name enthält den vollen Namen der Linie, bspw. „7 Avenue Express“.
    • short_name enthält den Kurznamen der Linie. Dabei handelt es sich normalerweise um eine Nummer, bspw. „M7“ oder „355“.
    • color enthält die Farbe, die im Liniennetz als Kennfarbe für diese Linie verwendet wird. Die Farbe wird als Hexadezimalwert wie z. B. #FF0033 angegeben.
    • agencies enthält ein Array mit TransitAgency-Objekten, die jeweils Informationen zum Beförderungsunternehmen der Linie liefern. Dazu gehören:
      • name: der Name des Beförderungsunternehmens.
      • url: die URL des Beförderungsunternehmens.
      • phone: die Telefonnummer des Beförderungsunternehmens.

      Sie müssen die Namen und URLs der Beförderungsunternehmen auf der Route angeben.

    • url enthält die URL für die Linie wie vom Beförderungsunternehmen angegeben.
    • icon enthält die URL für das mit dieser Linie verbundene Symbol.
    • text_color enthält die Textfarbe, die für die Kennzeichnung dieser Linie verwendet wird. Die Farbe wird als Hexadezimalwert angegeben.
    • vehicle enthält das auf dieser Linie eingesetzte Fahrzeug. Dazu können folgende Eigenschaften gehören:
      • name enthält die Bezeichnung des Fahrzeugs auf dieser Linie, bspw. „U-Bahn“.
      • type enthält den Fahrzeugtyp. In der Dokumentation zu den Fahrzeugtypen finden Sie eine vollständige Liste der unterstützten Werte.
      • icon enthält die URL für das mit diesem Fahrzeugtyp verbundene Symbol.
      • local_icon enthält die URL für das mit diesem Fahrzeugtyp verbundene Symbol, basierend auf der Kennzeichnung für Nahverkehr.

Fahrzeugtyp

Die Eigenschaft vehicle.type kann die folgenden Werte zurückgeben:

Wert Definition
RAIL Bahn
METRO_RAIL Stadtbahn
SUBWAY U-Bahn
TRAM Straßenbahn
MONORAIL Einschienenbahn
HEAVY_RAIL Stadtschnellbahn
COMMUTER_TRAIN Nahverkehr
HIGH_SPEED_TRAIN Schnellzug
BUS Bus
INTERCITY_BUS Fernbus
TROLLEYBUS Oberleitungsbus
SHARE_TAXI Sammeltaxi
FERRY Fähre
CABLE_CAR A vehicle that operates on a cable, usually on the ground. Luftseilbahnen können zum Typ GONDOLA_LIFT gehören.
GONDOLA_LIFT Gondelbahn, eine Art Luftseilbahn.
FUNICULAR Standseilbahn. Besteht normalerweise aus zwei Wagen, von denen einer als Gegengewicht zum anderen dient.
OTHER Alle anderen Fahrzeuge geben diesen Typ zurück.

Verfügbare Verkehrsmittel

Das Antwortfeld available_travel_modes enthält ein Array mit verfügbaren Verkehrsmitteln. Dieses Feld wird zurückgegeben, wenn in einer Anforderung ein Verkehrsmittel (mode) angegeben wird und keine Ergebnisse zurückgegeben werden. Das Array enthält die verfügbaren Verkehrsmittel in den Ländern der vorgegebenen Gruppe von Wegpunkten, für die keine Ergebnisse vorhanden sind. Das Feld wird nicht zurückgegeben, wenn es sich bei keinem der Wegpunkte um Wegpunkte vom Typ via: handelt.

Führen Sie beispielsweise die folgende Anforderung aus:

https://maps.googleapis.com/maps/api/directions/json?&mode=transit&origin=frontera+el+hierro&destination=la+restinga+el+hierro&departure_time=1399995076&key=YOUR_API_KEY

Dadurch wird die folgende Antwort erzeugt:

{
   "available_travel_modes" : [ "DRIVING", "BICYCLING", "WALKING" ],
   "geocoded_waypoints" : [
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJwZNMti1fawwRO2aVVVX2yKg",
         "types" : [ "locality", "political" ]
      },
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJ3aPgQGtXawwRLYeiBMUi7bM",
         "types" : [ "locality", "political" ]
      }
   ],
   "routes" : [],
   "status" : "ZERO_RESULTS"
}

Der Parameter sensor

Bisher war in der Google Maps API die Angabe des Parameters sensor erforderlich. Damit wurde festgelegt, ob seitens der Anwendung ein Sensor zur Ermittlung des Benutzerstandorts verwendet wurde. Dieser Parameter wird nicht mehr benötigt.

Feedback geben zu...

Google Maps Directions API
Google Maps Directions API