Distance Matrix API-Anfrage und -Antwort

Einführung

Eine Distance Matrix API-Anfrage weist die folgende Form auf:

https://maps.googleapis.com/maps/api/distancematrix/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 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 ihrer möglichen Werte finden Sie unten.

Erforderliche Parameter

• Ziele

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

• Ursprünge

  Der Ausgangspunkt für die Berechnung von Entfernung und Zeit. Sie können einen oder mehrere Orte angeben, die durch das Pipe-Zeichen (|) getrennt sind, in Form einer Orts-ID, einer Adresse oder von Breiten- und Längengradkoordinaten:

  • 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 unterscheiden, die von der Geocoding API zurückgegeben wird, z. B. ein Gebäudeeingang anstelle des Zentrums.
    Hinweis: Die Verwendung von Orts-IDs wird gegenüber der Verwendung von Adressen oder Breiten-/Längengradkoordinaten bevorzugt. Wenn Sie Koordinaten verwenden, wird der Punkt immer auf die Straße gesetzt, die diesen Koordinaten am nächsten ist. Das ist möglicherweise keine Zufahrt zum Grundstück oder sogar eine Straße, die nicht schnell oder sicher zum Ziel führt. Wenn Sie die Adresse verwenden, wird die Entfernung zur Mitte des Gebäudes angegeben, nicht zu einem Eingang des Gebäudes.
  • Koordinaten: Wenn Sie Breiten-/Längengradkoordinaten übergeben, werden diese an die nächstgelegene Straße angedockt. Die Übergabe einer Orts-ID wird bevorzugt. Wenn Sie Koordinaten übergeben, achten Sie darauf, dass zwischen den Breiten- und Längengradwerten kein Leerzeichen vorhanden ist.
  • Plus Codes müssen als globaler oder als zusammengesetzter Code formatiert werden. Formatieren Sie die Plus Codes wie hier gezeigt (Pluszeichen werden in der URL als %2B dargestellt, Leerzeichen als %20):
    • Global Code besteht aus einem vierstelligen Code für das Gebiet und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9 wird zu 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 viele Ausgangspunkte haben, da die URL bei Verwendung einer codierten Polylinie deutlich kürzer ist.
    • Codierte Polylinien müssen mit enc: beginnen und mit einem Doppelpunkt : enden. 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 ÖPNV-Routen an, in Sekunden seit Mitternacht am 1. Januar 1970 UTC. Sie können entweder departure_time oder arrival_time angeben, aber nicht beides. arrival_time muss als Ganzzahl angegeben werden.

• vermeiden

  Entfernungen können auch unter Berücksichtigung bestimmter Einschränkungen berechnet werden. Einschränkungen werden durch die Verwendung des Parameters „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 für die berechnete Route Mautstraßen/-brücken vermieden werden sollen.
  • highways gibt an, dass für die berechnete Route Autobahnen vermieden werden sollen.
  • ferries gibt an, dass die berechnete Route Fähren vermeiden soll.
  • indoor gibt an, dass die berechnete Route bei Wegbeschreibungen für Fußgänger und öffentliche Verkehrsmittel keine Treppen in Innenräumen enthalten soll.

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

  Hinweis: Das Hinzufügen von Einschränkungen schließt Routen, die die eingeschränkte Funktion enthalten, nicht aus. Es führt jedoch dazu, dass das Ergebnis auf günstigere Routen ausgerichtet wird.

• departure_time

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

  • Für Anfragen mit öffentlichen Verkehrsmitteln als Mobilitätsform: Optional können Sie departure_time oder arrival_time angeben. Wenn keine der beiden Zeiten angegeben ist, wird für departure_time standardmäßig die aktuelle Uhrzeit verwendet.
  • Für Anfragen mit Kraftfahrzeugen als Mobilitätsform: Sie können die departure_time angeben, um eine Route und eine Fahrtdauer (Antwortfeld: duration_in_traffic) zu erhalten, bei denen die Verkehrslage berücksichtigt wird. Für departure_time muss die aktuelle Zeit oder eine Zeit in der Zukunft festgelegt 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: „Distance Matrix“-Anfragen, in denen departure_time angegeben ist, wenn mode=driving festgelegt ist, sind auf maximal 100 Elemente pro Anfrage beschränkt. Die Anzahl der Elemente ergibt sich aus der Anzahl der Startpunkte 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. Diese Liste ist daher möglicherweise nicht vollständig.
  • Wenn language nicht angegeben ist, versucht die API, die bevorzugte Sprache zu verwenden, die im Accept-Language-Header angegeben ist.
  • Die API versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Straßenadressen in der lokalen Sprache zurückgegeben, die bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert werden. Dabei wird die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Alle Adresskomponenten werden in derselben Sprache zurückgegeben, die anhand der ersten Komponente ausgewählt wird.
  • Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, wird die nächstgelegene Übereinstimmung verwendet.
  • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die von der API zurückgegeben werden, und auf 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 sein können, 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 DRIVING-Modus verwendet. Standardmäßig erfolgt die Routenberechnung mit dem Wert driving . Die folgenden 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 verfügbar) angefordert.
  • Bei transit werden Routen oder Entfernungen mit öffentlichen Verkehrsmitteln angefordert (sofern verfügbar). Wenn Sie den Modus auf „transit“ 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. Optional können Sie auch ein transit_mode- und/oder ein transit_routing_preference-Element einfügen.
  Hinweis: Sowohl Fußgänger- als auch Fahrradrouten enthalten unter Umständen keine ausgewiesenen Fußgänger- oder Radwege. In diesen Fällen werden Warnungen im zurückgegebenen Ergebnis zurückgegeben, die Sie dem Nutzer anzeigen müssen.
  Hinweis: ÖPNV-Fahrten sind bis zu 7 Tage in der Vergangenheit oder bis zu 100 Tage in der Zukunft verfügbar, sofern die ÖPNV-Informationen von Datenanbietern bereitgestellt werden. Fahrpläne für öffentliche Verkehrsmittel ändern sich häufig. Die verfügbaren Fahrten mit öffentlichen Verkehrsmitteln können sich im Laufe der Zeit ändern. Es gibt keine Garantie, dass Vorhersagen, die weit im Voraus getroffen werden, konsistente Ergebnisse liefern.

• Region

  Der Regionscode, angegeben als zweistelliger Ländercode der Top-Level-Domain (ccTLD). Die meisten ccTLD-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs ist beispielsweise „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für das Land „Vereinigtes Königreich Großbritannien und Nordirland“).

• traffic_model

  Gibt die Annahmen an, die bei der Berechnung der Zeit im Verkehr verwendet werden sollen. Diese Einstellung wirkt sich auf den Wert aus, der in der Antwort im Feld „duration_in_traffic“ zurückgegeben wird. Dieser enthält die voraussichtliche Reisezeit, die anhand bisheriger Durchschnittswerte berechnet wird. Der Parameter traffic_model darf nur für Kraftfahrzeugrouten 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 als die tatsächliche Reisezeit sein sollte. 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 von best_guess liefert für die meisten Anwendungsfälle die nützlichsten Vorhersagen. Es ist möglich, dass die Vorhersage der Reisezeit für best_guess kürzer als für optimistic oder länger als für pessimistic ist, da im Vorhersagemodell für best_guess Verkehrsinformationen in Echtzeit berücksichtigt werden.

• transit_mode

  Gibt ein oder mehrere bevorzugte Verkehrsmittel an. Dieser Parameter darf nur für Routen mit öffentlichen Verkehrsmitteln 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 mit öffentlichen Verkehrsmitteln 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 mit Breiten- und Längengrad angegeben:

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 -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 Koordinaten des Ziels anzugeben:

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

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

Dieses Beispiel zeigt dieselbe Anfrage mit einer codierten Polylinie:

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 -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 der folgenden Bedingungen zutreffen (sie sind erforderlich, um das Feld duration_in_traffic in der Distance Matrix-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 einfügen, um die Annahmen anzugeben, die bei der Berechnung der Zeit im Verkehr verwendet werden sollen.

Mit der folgenden URL wird eine Distance Matrix-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 Distance Matrix-Antwort zurückzugeben.

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

{
  "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",
}

 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 eine Richtung an, um die richtige Fahrtrichtung festzulegen.

Festlegen, dass berechnete Routen auf einer bestimmten Straßenseite verlaufen müssen

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

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 -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 die Anpassung auf jeden Ort entlang der Polylinie angewendet. In den beiden Zielen in dieser Anfrage wird beispielsweise der Parameter verwendet:

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 -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 Modifizierer side_of_road: darf nur unter dieser Einschränkung verwendet werden:

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

Festlegen, dass berechnete Routen eine bestimmte Ausrichtung haben sollen

Wenn Sie einen Ort angeben, können Sie festlegen, dass die berechnete Route in einer bestimmten Richtung durch den Ort verläuft. Diese Überschrift 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 Grad gibt den Norden an, 90 Grad den Osten usw. im Uhrzeigersinn. In dieser Anfrage verläuft die berechnete Route beispielsweise zuerst östlich vom Startpunkt und macht dann eine Kehrtwende:

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 -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 heading=X:-Modifikator darf nur unter 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 für denselben Standort nicht angegeben.
• Der Ort wird mit einem Breiten-/Längengradwert angegeben. Sie dürfen heading nicht mit Adressen, Orts-IDs oder codierten Polylinien verwenden.

„Distance Matrix“-Anfragen und -Antworten

Unten sehen Sie eine Beispiel-HTTP-Anfrage, in der Entfernung und Dauer von Vancouver, BC, Kanada, und von Seattle, WA, USA, nach San Francisco, CA, USA, und nach Victoria, BC, Kanada, angefordert werden.

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 -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:

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

{
  "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",
}

 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

DistanceMatrixStatus

Statuscodes, die vom Dienst zurückgegeben werden.

• 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 das Limit pro Anfrage.
• OVER_DAILY_LIMIT weist auf eines der folgenden Probleme hin:
  • 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 „Distance Matrix“-Anfrage aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Die Anfrage ist möglicherweise erfolgreich, wenn Sie es erneut versuchen.

DistanceMatrixRow

DistanceMatrixElement

Preis

Der Gesamtfahrpreis für die Route.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

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.