Anfrage und Antwort der Distance Matrix API (alte Version)

Entwickler im Europäischen Wirtschaftsraum (EWR)

Einführung

Eine Distance Matrix API (Legacy)-Anfrage hat das folgende Format:

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

Dabei kann outputFormat einer der folgenden Werte sein:

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

Bestimmte Parameter sind erforderlich, während andere optional sind. Wie in URLs üblich, werden alle Parameter mit dem Und-Zeichen (&) getrennt. Alle reservierten Zeichen (z. B. das Pluszeichen „+“) müssen URL-codiert sein. Die Liste der Parameter und ihre möglichen Werte sind unten aufgeführt.

Erforderliche Parameter

  • Ziele

    Ein oder mehrere Orte, die als Ziel für die Berechnung der Entfernung und Reisezeit verwendet werden sollen. Die Optionen für den Parameter „destinations“ sind dieselben wie für den Parameter „origins“.

  • origins

    Der Ausgangspunkt für die Berechnung der Entfernung und Reisezeit. Sie können einen oder mehrere Orte angeben, die durch einen senkrechten Strich (|) getrennt sind. Die Angabe kann in Form einer Orts-ID, einer Adresse oder von Breiten- und Längengradkoordinaten erfolgen:

    • Orts-ID: Wenn Sie eine Orts-ID angeben, müssen Sie ihr das Präfix place_id: voranstellen.
    • Adresse: Wenn Sie eine Adresse übergeben, wird der String vom Dienst geocodiert und in Breiten- und Längengradkoordinaten umgewandelt, um die Entfernung zu berechnen. Diese Koordinate kann sich von der von der Geocoding API zurückgegebenen Koordinate unterscheiden, z. B. ein Gebäudeeingang anstelle der Gebäudemitte.
      Hinweis: Orts-IDs sind Adressen oder Breiten-/Längengradkoordinaten vorzuziehen. Wenn Sie Koordinaten verwenden, wird der Punkt immer an der Straße ausgerichtet, die diesen Koordinaten am nächsten liegt. Das ist möglicherweise kein Zugangspunkt zum Grundstück oder keine Straße, die schnell oder sicher zum Ziel führt. Wenn Sie die Adresse verwenden, wird die Entfernung zur Mitte des Gebäudes und nicht zu einem Eingang des Gebäudes angegeben.
    • Koordinaten: Wenn Sie Breiten-/Längengradkoordinaten übergeben, werden sie an der nächstgelegenen Straße ausgerichtet. Es wird empfohlen, eine Orts-ID zu übergeben. Wenn Sie Koordinaten übergeben, darf zwischen den Werten für Breiten- und Längengrad kein Leerzeichen stehen.
    • Plus Codes müssen als globaler oder zusammengesetzter Code formatiert sein. Formatieren Sie die Plus Codes wie hier gezeigt (Pluszeichen werden in der URL als %2B dargestellt, Leerzeichen als %20):
      • Global Code besteht aus einer vierstelligen Vorwahl und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9 wird als 849VCWC8%2BR9 codiert).
      • Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort (CWC8+R9 Mountain View, CA, USA wird zu CWC8%2BR9%20Mountain%20View%20CA%20USA codiert).
    • Codierte Polylinie: Alternativ können Sie einen codierten Satz von Koordinaten mit dem Algorithmus für codierte Polylinien angeben. Das ist besonders nützlich, wenn Sie eine große Anzahl von Startpunkten haben, da die URL bei Verwendung einer codierten Polylinie deutlich kürzer ist.
      • Codierten Polylinien muss das Präfix enc: vorangestellt werden, gefolgt von einem Doppelpunkt :. Beispiel: origins=enc:gfo}EtohhU:
      • Sie können auch mehrere codierte Polylinien angeben, die durch das Pipe-Zeichen | getrennt sind. Beispiel: 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

Optionale Parameter

  • arrival_time

    Gibt die bevorzugte Ankunftszeit für Routen für öffentliche Verkehrsmittel in Sekunden seit Mitternacht am 1. Januar 1970 UTC an. Sie können entweder departure_time oder arrival_time angeben, aber nicht beides. Beachten Sie, dass arrival_time als Ganzzahl angegeben werden muss.

  • avoid

    Entfernungen können auch unter Berücksichtigung bestimmter Einschränkungen berechnet werden. Einschränkungen werden durch den Parameter „avoid“ und ein Argument für diesen Parameter angegeben, das die zu vermeidende Einschränkung angibt. Die folgenden Einschränkungen werden unterstützt:

    • tolls gibt an, dass auf der berechneten Route Mautstraßen und ‑brücken vermieden werden sollen.
    • highways gibt an, dass auf der berechneten Route Autobahnen vermieden werden sollen.
    • ferries gibt an, dass auf der berechneten Route Fähren vermieden werden sollen.
    • indoor gibt an, dass für die berechnete Route Treppen in Innenräumen für Fußgänger und Routen für öffentliche Verkehrsmittel vermieden werden sollen.

    Sie können eine Route anfordern, bei der Mautstraßen, Autobahnen und Fähren vermieden werden, indem Sie beide Einschränkungen an den Parameter „avoid“ übergeben. Beispiel: avoid=tolls|highways|ferries

    Hinweis: Durch das Hinzufügen von Einschränkungen werden Routen, die das eingeschränkte Element enthalten, nicht ausgeschlossen. Das Ergebnis wird jedoch zugunsten günstigerer Routen beeinflusst.

  • departure_time

    Gibt die bevorzugte Abfahrtszeit an. Sie können die Zeit als Ganzzahl in Sekunden seit dem 1. Januar 1970, 00:00 Uhr UTC angeben. Wenn ein departure_time nach dem 31.12.9999, 23:59:59.999999999Z angegeben wird, setzt die API den departure_time auf den 31.12.9999, 23:59:59.999999999Z zurück. Alternativ können Sie den Wert „now“ angeben, wodurch die Abfahrtszeit auf die aktuelle Zeit (auf die Sekunde genau) festgelegt wird. Die Abreisezeit kann in zwei Fällen angegeben werden:

    • Für Anfragen mit öffentlichen Verkehrsmitteln als Mobilitätsform: Sie können optional departure_time oder arrival_time angeben. Wenn keine der beiden Zeiten angegeben ist, wird für departure_time standardmäßig die aktuelle Uhrzeit verwendet (d. h. die Abfahrtszeit entspricht der aktuellen Uhrzeit).
    • Für Anfragen mit Kraftfahrzeugen als Mobilitätsform: Sie können departure_time angeben, um eine Route und eine Reisedauer (Antwortfeld: duration_in_traffic) zu erhalten, die die Verkehrslage berücksichtigen. Für departure_time muss die aktuelle Zeit oder eine Zeit in der Zukunft angegeben werden. Der Wert darf nicht in der Vergangenheit liegen.
    Hinweis: Wenn keine Startzeit angegeben ist, beruhen die Auswahl der Route und die Reisezeit auf dem Straßennetz und der durchschnittlichen zeitunabhängigen Verkehrslage. Die Ergebnisse für eine bestimmte Anfrage können sich im Laufe der Zeit aufgrund von Änderungen im Straßennetz, Aktualisierungen der durchschnittlichen Verkehrslage und der Dezentralisierung des Diensts ändern. Außerdem können die Ergebnisse zwischen praktisch gleichwertigen Routen jederzeit und beliebig oft variieren.
    Hinweis: Distanzmatrix-Anfragen, in denen departure_time angegeben ist, wenn mode=driving, sind auf maximal 100 Elemente pro Anfrage beschränkt. Die Anzahl der Elemente ergibt sich aus der Anzahl der Startorte multipliziert mit der Anzahl der Zielorte.

  • Sprache

    Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.

    • Hier finden Sie eine Liste der unterstützten Sprachen. Die unterstützten Sprachen werden regelmäßig von Google aktualisiert, sodass diese Liste unter Umständen nicht vollständig ist.
    • Wenn language nicht angegeben ist, versucht die API, die im Header Accept-Language angegebene bevorzugte Sprache zu verwenden.
    • Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Adressen in der Landessprache zurückgegeben, die bei Bedarf in eine für den Nutzer lesbare Schrift transliteriert werden. Dabei wird die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die von der ersten Komponente ausgewählt wird.
    • Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die nächstgelegene Übereinstimmung.
    • Die bevorzugte Sprache hat einen geringen Einfluss auf die von der API zurückgegebenen Ergebnisse und die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sind, in einer anderen jedoch nicht. Beispiel: utca und tér sind Synonyme für „Straße“ auf Ungarisch.

  • Modus

    Für die Berechnung von Entfernungen und Wegbeschreibungen können Sie die zu verwendende Mobilitätsform angeben. Standardmäßig wird der Modus DRIVING verwendet. Standardmäßig erfolgt die Routenberechnung mit dem Wert driving . Folgende Mobilitätsformen werden unterstützt:

    • Bei driving (Standardeinstellung) wird eine standardmäßige Wegbeschreibung oder Entfernung auf Grundlage des Straßennetzes angefordert.
    • Bei walking werden Fußgängerrouten oder Entfernungen auf Fußgängerwegen und Bürgersteigen (sofern vorhanden) angefordert.
    • Bei bicycling werden Fahrradrouten oder Entfernungen mit Radwegen und bevorzugten Straßen (sofern vorhanden) angefordert.
    • Bei transit werden Routen oder Entfernungen mit öffentlichen Verkehrsmitteln (sofern verfügbar) angefordert. Wenn Sie den Modus auf „Öffentliche Verkehrsmittel“ festlegen, können Sie optional entweder departure_time oder arrival_time angeben. Wenn keine der beiden Zeiten angegeben ist, wird für departure_time standardmäßig die aktuelle Uhrzeit verwendet (d. h. die Abfahrtszeit entspricht der aktuellen Uhrzeit). Optional können Sie auch eine transit_mode und/oder eine transit_routing_preference angeben.
    Hinweis: Fußgänger- und Fahrradrouten enthalten unter Umständen keine ausgewiesenen Fußgänger- oder Fahrradwege. In diesen Fällen werden Warnungen im zurückgegebenen Ergebnis zurückgegeben, die Sie dem Nutzer anzeigen müssen.
    Hinweis: Fahrten mit öffentlichen Verkehrsmitteln sind bis zu 7 Tage in der Vergangenheit oder bis zu 100 Tage in der Zukunft verfügbar, sofern die entsprechenden Informationen von Datenanbietern bereitgestellt werden. Fahrpläne ändern sich häufig, verfügbare Fahrten können sich im Laufe der Zeit ändern und es gibt keine Garantie für konsistente Ergebnisse bei Vorhersagen, die weit im Voraus getroffen werden.

  • Region

    Der Regionscode, angegeben als zweistelliger Wert der Ländercode-Top-Level-Domain (ccTLD). Die meisten ccTLD-Codes entsprechen den ISO-3166-1-Codes. Es gibt jedoch einige Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk), der ISO-3166-1-Code dagegen „gb“ (technisch gesehen für die Entität „Vereinigtes Königreich Großbritannien und Nordirland“).

  • traffic_model

    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. Der Parameter traffic_model darf nur für Wegbeschreibungen angegeben werden, wenn die Anfrage einen departure_time enthält. Verfügbare Werte für diesen Parameter sind:

    • best_guess (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 departure_time rückt.
    • pessimistic gibt an, dass die zurückgegebene duration_in_traffic an den meisten Tagen länger sein sollte als die tatsächliche Reisezeit. 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.

    Der Standardwert best_guess liefert für die meisten Anwendungsfälle die nützlichsten Vorhersagen. Es ist möglich, dass die Vorhersage der Reisedauer für best_guess kürzer als optimistic oder länger als pessimistic ist, da das Vorhersagemodell für best_guess Echtzeit-Verkehrsinformationen einbezieht.

  • transit_mode

    Gibt ein oder mehrere bevorzugte Verkehrsmittel an. Dieser Parameter darf nur für Routen für öffentliche Verkehrsmittel angegeben werden. Der 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 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.
    • 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 Einstellungen für Routen mit öffentlichen Verkehrsmitteln an. Mit diesem Parameter können Sie die zurückgegebenen Optionen beeinflussen, anstatt die standardmäßige beste Route der API zu verwenden. Dieser Parameter darf nur für Routen für öffentliche Verkehrsmittel angegeben werden. Dieser Parameter unterstützt die folgenden Argumente:

    • less_walking gibt an, dass die berechnete Route möglichst wenige Gehstrecken enthalten soll.
    • fewer_transfers gibt an, dass die berechnete Route möglichst wenige Umstiege beinhalten soll.

  • Einheiten

    Gibt das Einheitensystem an, das beim Anzeigen von Ergebnissen verwendet werden soll.

    Hinweis: Die Einstellung für das Einheitensystem wirkt sich nur auf den Text aus, der in Entfernungsfeldern angezeigt wird. Die Entfernungsfelder enthalten auch Werte, die immer in Metern angegeben werden.

Beispielanfragen

In diesem Beispiel werden die Zielkoordinaten mithilfe von Breiten- und Längengraden angegeben:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

In diesem Beispiel werden Plus Codes verwendet, um die Zielkoordinaten anzugeben:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

In diesem Beispiel wird dieselbe Anfrage mit einer codierten Polylinie verwendet:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

Verkehrsinformationen

Verkehrsinformationen werden verwendet, wenn alle folgenden Bedingungen zutreffen (sie sind erforderlich, um das Feld duration_in_traffic in der Distanzmatrix-Antwort zu erhalten):

  • Der Parameter mode ist driving oder nicht angegeben (driving ist die Standardmobilitätsform).
  • Die Anfrage enthält einen gültigen Parameter departure_time. Für departure_time kann die aktuelle oder eine Zeit in der Zukunft festgelegt werden. Der Wert darf nicht in der Vergangenheit liegen.

Optional können Sie den Parameter traffic_model in Ihre Anfrage aufnehmen, um die Annahmen anzugeben, die bei der Berechnung der Reisezeit verwendet werden sollen.

Mit der folgenden URL wird eine Distanzmatrix-Anfrage für die Fahrstrecken zwischen Boston, MA oder Charlestown, MA und Lexington, MA und Concord, MA initiiert. Die Anfrage enthält eine Abfahrtszeit und erfüllt alle Anforderungen, um das Feld duration_in_traffic in der Distanzmatrix-Antwort zurückzugeben.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

JSON

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

Standortmodifikatoren

Mit Standortmodifikatoren können Sie angeben, aus welcher Richtung die Fahrer einen bestimmten Standort anfahren sollen. Verwenden Sie dazu den Modifikator side_of_road, um die Straßenseite anzugeben, oder geben Sie einen Kurs an, um die richtige Fahrtrichtung anzugeben.

Festlegen, dass berechnete Routen über eine bestimmte Straßenseite führen müssen

Wenn Sie einen Ort angeben, können Sie mit dem Präfix side_of_road: festlegen, dass die berechnete Route über die Straßenseite führen soll, auf der sich der Wegpunkt befindet. Mit dieser Anfrage wird beispielsweise die Entfernung für eine lange Route zurückgegeben, sodass das Fahrzeug auf der Straßenseite endet, auf der sich der Wegpunkt befindet:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

Wenn Sie side_of_road: mit codierten Polylinien verwenden, wird der Modifikator auf jeden Ort entlang der Polylinie angewendet. Beispielsweise verwenden die beiden Ziele in dieser Anfrage den Parameter:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

Der Modifikator side_of_road: darf nur mit dieser Einschränkung verwendet werden:

  • Der Parameter mode ist driving oder nicht angegeben (driving ist die Standardmobilitätsform).

Angeben, dass berechnete Routen einen bestimmten Kurs haben sollen

Wenn Sie einen Ort angeben, können Sie festlegen, dass die berechnete Route in einer bestimmten Richtung durch den Ort verlaufen soll. Dieser Kurs wird mit dem Präfix heading=X: angegeben, wobei X ein ganzzahliger Gradwert zwischen 0 (einschließlich) und 360 (ausschließlich) ist. Ein Kurs von 0 zeigt nach Norden, 90 nach Osten und so weiter im Uhrzeigersinn. In dieser Anfrage führt die berechnete Route beispielsweise vom Startpunkt aus nach Osten und macht dann eine Kehrtwende:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

Der Modifikator heading=X: darf nur mit den folgenden Einschränkungen verwendet werden:

  • Der Parameter mode ist driving, bicycling oder nicht angegeben (driving ist die Standardmobilitätsform).
  • Der Modifikator side_of_road ist nicht für denselben Standort angegeben.
  • Der Standort wird mit einem Breiten-/Längengradwert angegeben. Sie dürfen heading nicht mit Adressen, Orts-IDs oder codierten Polylinien verwenden.

Distanzmatrix-Anfragen und -Antworten

Im Folgenden finden Sie eine HTTP-Beispielanfrage, mit der die Entfernung und Dauer von Vancouver, BC, Kanada und Seattle, WA, USA nach San Francisco, CA, USA und Victoria, BC, Kanada angefordert werden.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

Diese Anforderung gibt vier Elemente zurück - zwei Ursprungsorte mal zwei Zielorte:

Vancouver nach San Francisco Vancouver nach Victoria
Seattle nach San Francisco Seattle nach Victoria

Die Ergebnisse werden in Zeilen zurückgegeben, wobei jede Zeile einen Startort enthält, der mit jedem Zielort kombiniert ist.

JSON

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

DistanceMatrixResponse

Feld Erforderlich Typ Beschreibung
required Array<string>

Ein Array von Adressen, die von der API aus Ihrer ursprünglichen Anfrage zurückgegeben wurden. Wie bei origin_addresses werden diese gegebenenfalls lokalisiert. Der Inhalt ist so zu lesen, wie er ist. Die formatierten Adressen dürfen nicht programmatisch geparst werden.

required Array<string>

Ein Array von Adressen, die von der API aus Ihrer ursprünglichen Anfrage zurückgegeben wurden. Diese werden vom Geocoder formatiert und entsprechend dem mit der Anfrage übergebenen Sprachparameter lokalisiert. Der Inhalt ist so zu lesen, wie er ist. Die formatierten Adressen dürfen nicht programmatisch geparst werden.

required Array<DistanceMatrixRow>

Ein Array von Elementen, die jeweils ein status-, duration- und distance-Element enthalten.

Weitere Informationen finden Sie unter DistanceMatrixRow.

required DistanceMatrixStatus

Enthält den Status der Anfrage und evtl. Debugging-Informationen, mit deren Hilfe Sie herausfinden können, warum die Anfrage zu Fehlern geführt hat.

Weitere Informationen finden Sie unter DistanceMatrixStatus.

optional String

Ein String, der den menschenlesbaren Text aller Fehler enthält, die bei der Verarbeitung der Anfrage aufgetreten sind.

DistanceMatrixStatus

Vom Dienst zurückgegebene Statuscodes.

  • OK gibt an, dass die Antwort ein gültiges Ergebnis enthält.
  • INVALID_REQUEST gibt an, dass die Anfrage ungültig war.
  • MAX_ELEMENTS_EXCEEDED: Das Produkt aus Start- und Zielorten überschreitet die Begrenzung pro Anfrage.
  • MAX_DIMENSIONS_EXCEEDED: Die Anzahl der Start- oder Zielorte überschreitet die Begrenzung pro Anfrage.
  • OVER_DAILY_LIMIT gibt einen der folgenden Werte an:
    • Der API-Schlüssel fehlt oder ist ungültig.
    • Die Abrechnung wurde für Ihr Konto nicht aktiviert.
    • Das von Ihnen festgelegte Nutzungslimit wurde überschritten.
    • Die angegebene Zahlungsmethode ist nicht mehr gültig. Das kann z. B. bei einer abgelaufenen Kreditkarte der Fall sein.
  • OVER_QUERY_LIMIT gibt an, dass der Dienst innerhalb des zulässigen Zeitraums zu viele Anfragen von Ihrer Anwendung erhalten hat.
  • REQUEST_DENIED gibt an, dass die Verwendung des „Distance Matrix“-Diensts durch Ihre Anwendung abgelehnt wurde.
  • UNKNOWN_ERROR gibt an, dass eine Distanzmatrix-Anfrage aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Die Anfrage ist möglicherweise erfolgreich, wenn Sie es erneut versuchen.

DistanceMatrixRow

Feld Erforderlich Typ Beschreibung
required Array<DistanceMatrixElement>

Wenn die Distance Matrix API Ergebnisse zurückgibt, werden sie in einem JSON-Zeilenarray platziert. Auch wenn keine Ergebnisse zurückgegeben werden (z. B. wenn die Start- und/oder Zielorte nicht vorhanden sind), wird ein leeres Array zurückgegeben.

Die Zeilen werden nach den Werten im Parameter „origin“ der Anfrage sortiert. Jede Zeile entspricht einem Startort und jedes Element in dieser Zeile entspricht einem Paar aus dem Startort und einem Zielwert.

Jedes Zeilenarray enthält einen oder mehrere Elementeinträge, die wiederum die Informationen zu einem einzelnen Start-Ziel-Paar enthalten.

Weitere Informationen finden Sie unter DistanceMatrixElement.

DistanceMatrixElement

Feld Erforderlich Typ Beschreibung
required DistanceMatrixElementStatus

Ein Status für das Element.

Weitere Informationen finden Sie unter DistanceMatrixElementStatus.

optional TextValueObject

Die Gesamtstrecke dieser Route in Metern (Wert) und als Text. Der Textwert verwendet das Einheitensystem, das mit dem Parameter „unit“ der ursprünglichen Anfrage oder der Region des Startpunkts angegeben wurde.

Weitere Informationen finden Sie unter TextValueObject.

optional TextValueObject

Die Reisezeit in Sekunden (Feld „value“) und als Text. Die Textdarstellung wird entsprechend dem Sprachparameter der Abfrage lokalisiert.

Weitere Informationen finden Sie unter TextValueObject.

optional TextValueObject

Die Reisezeit für diese Route, basierend auf der aktuellen und historischen Verkehrslage. Informationen zu den Optionen, mit denen Sie anfordern können, dass der zurückgegebene Wert optimistisch, pessimistisch oder eine Schätzung ist, finden Sie im Anfrageparameter traffic_model. Die Dauer wird in Sekunden (im Feld „value“) und als Text angegeben. Die Textdarstellung wird entsprechend dem Sprachparameter der Abfrage lokalisiert. Die Dauer unter Berücksichtigung der Verkehrslage wird nur zurückgegeben, wenn alle der folgenden Bedingungen erfüllt sind:

  • Die Anfrage enthält einen departure_time-Parameter.
  • Für die angeforderte Route sind Informationen zur Verkehrslage verfügbar.
  • Der Parameter „mode“ ist auf „driving“ festgelegt.

Weitere Informationen finden Sie unter TextValueObject.

optional Fahrpreis

Falls vorhanden, enthält dieses Feld 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 der entsprechende Anbieter Fahrpreisinformationen zur Verfügung stellt.

Weitere Informationen finden Sie unter Fahrpreis.

Preis

Der Gesamtfahrpreis für die Route.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
Feld Erforderlich Typ Beschreibung
erforderlich String

Ein Währungscode nach ISO 4217 für die Währung des Betrags.

text

required String

Der Gesamtbetrag im Format der angeforderten Sprache.
required Zahl

Der Gesamtfahrpreis in der angegebenen Währung.

DistanceMatrixElementStatus

  • OK gibt an, dass die Antwort ein gültiges Ergebnis enthält.
  • NOT_FOUND gibt an, dass der Start- und/oder Zielort dieses Paars nicht geocodiert werden konnte.
  • ZERO_RESULTS gibt an, dass keine Route zwischen Start- und Zielort gefunden werden konnte.
  • MAX_ROUTE_LENGTH_EXCEEDED gibt an, dass die angeforderte Route zu lang ist und nicht verarbeitet werden kann.

TextValueObject

Ein Objekt, das einen numerischen Wert und seine formatierte Textdarstellung enthält.

Feld Erforderlich Typ Beschreibung

text

erforderlich String

Stringwert.
required Zahl

Numerischer Wert.