Es kann losgehen!

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

Die Google Maps Distance Matrix 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 Distance Matrix API aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Entwickler-Leitfaden

Bei Google Maps Distance Matrix API handelt es sich um einen Dienst, der Reisezeiten und Entfernungen für eine Start- und Zielortmatrix bereitstellt.

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 Elemente pro Tag werden als die Summe der clientseitigen und serverseitigen Abfragen berechnet.

Dieses Dokument richtet sich an Entwickler, die Reisezeiten und Entfernungen zwischen mehreren Punkten mithilfe von Karten berechnen möchten, die über eine 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

Die Google Maps Distance Matrix API gibt Informationen basierend auf der empfohlenen Route zwischen den von der Google Maps API berechneten Start- und Zielpunkten zurück. Sie werden in zwei Zeilen mit Werten für duration und distance für jedes Paar dargestellt.

Von diesem Dienst werden keine detaillierten Routeninformationen geliefert. Diese Routeninformationen können Sie abrufen, indem Sie den gewünschten einzelnen Start- und Zielort an Google Maps Directions API übergeben.

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

Distance Matrix-Anforderungen

Eine Google Maps Distance Matrix API-Anforderung weist folgendes Format 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, oder
  • 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. Zudem sollten Sie beachten, dass für verschiedene Browser, Proxys und Server ebenfalls unterschiedliche URL-Zeichenbegrenzungen gelten können.

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 Distance Matrix API über HTTP Folgendes:

http://maps.googleapis.com/maps/api/distancematrix/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.

Erforderliche Parameter

  • origins – Der Startpunkt für die Berechnung der Reisezeit und Entfernung. 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 Dienst die Zeichenfolge und wandelt sie in Längengrad- und Breitengradkoordinaten um, um so die Entfernungen 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.
      origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON
    • Wenn Sie Längen- und Breitengradkoordinaten übergeben, werden diese unverändert zur Berechnung der Entfernung verwendet. Beachten Sie, dass sich zwischen den Werten für den Längen- und den Breitengrad kein Leerzeichen befinden darf.
      origins=41.43206,-81.38992|-33.86748,151.20699
    • 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.
      origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
    • 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 Startpunkten 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: origins=enc:gfo}EtohhU:
      • Sie können auch mehrere codierte Polylinien einfügen, die durch einen senkrechten Strich (|) voneinander getrennt sind. Beispiel: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
  • destinations – Ein oder mehrere Ort(e), der/die als Endpunkt für die Berechnung von Reisezeit und Entfernung verwendet wird/werden. Die Optionen für den Parameter destinations entsprechen den Optionen des oben beschriebenen Parameters origins.
  • 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 Distance Matrix-Anforderungen verwenden. Lesen Sie weitere Informationen zu Authentifizierungsparametern für Premium Plan-Kunden.

Im folgenden Beispiel werden Längen- und Breitengradkoordinaten zur Angabe der Zielkoordinaten verwendet:

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

Das folgende Beispiel enthält die gleiche Anforderung unter Verwendung einer codierten Polylinie:

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=enc:_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV:&key=YOUR_API_KEY

Optionale Parameter

  • mode (Standard: driving) — gibt das Transportmittel an, auf dem die Berechnung der Entfernung basieren soll. Die gültigen Werte und weitere Einzelheiten zu Anforderungen finden Sie im Abschnitt Transportmittel in diesem Dokument.
  • 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.
  • avoid — bindet Einschränkungen in die Route ein. Die zulässigen Werte finden Sie im Abschnitt Einschränkungen in diesem Dokument. Es kann jeweils nur eine Einschränkung angegeben werden.
  • units — gibt das Einheitensystem an, das zur Darstellung der Entfernung als Text verwendet werden soll. Weitere Informationen finden Sie im Abschnitt Einheitensysteme in diesem Dokument.
  • arrival_time – gibt die gewünschte Ankunftszeit bei Anforderungen 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.

      Hinweis: Distance Matrix-Anforderungen, mit denen die Abreisezeit (departure_time) angegeben wird, wenn mode=driving, sind auf maximal 100-Elemente pro Anforderung beschränkt. Durch die Anzahl der Startpunkte multipliziert mit der Anzahl der Zielorte wird die Anzahl der Elemente definiert.

  • 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 nur angegeben werden, wenn die Anforderung das Verkehrsmittel driving nutzt, einen Wert für departure_time aufweist 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.
  • transit_mode — gibt ein oder mehrere bevorzugte öffentliche Verkehrsmittel an. Dieser Parameter kann nur angegeben werden, wenn für mode der Wert transit angegeben ist. 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 angegeben werden, wenn für mode der Wert transit angegeben ist. 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.

Verkehrsmittel

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

  • driving (Standard) gibt an, dass die Entfernung unter Verwendung des Straßennetzes berechnet wird.
  • walking fordert eine Entfernungsberechnung für Fußgänger unter Verwendung von Fußwegen (sofern verfügbar) an.
  • bicycling fordert eine Entfernungsberechnung für Fahrradfahrer unter Verwendung von Radwegen und bevorzugten Straßen (sofern verfügbar) an.
  • transit fordert eine Entfernungsberechnung unter Verwendung von öffentlichen Verkehrsmitteln (sofern verfügbar) an. Dieser Wert kann nur angegeben werden, wenn die Anforderung einen API-Schlüssel oder eine Google Maps APIs Premium Plan-Client-ID enthält. 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: Routen für Fußgänger und Fahrradfahrer können ggf. neben Fuß- und Radwegen auch andere Wege/Straßen umfassen. In diesem Fall werden von den Antworten Warnungen (warnings) zurückgegeben, die dem Benutzer angezeigt werden müssen.

Einschränkungen

Entfernungen können auch 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
  • avoid=indoor

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

Einheitensysteme

Distance Matrix-Ergebnisse enthalten text in den Feldern distance, in denen die Entfernung der berechneten Route angegeben wird. Das zu verwendende Einheitensystem kann festgelegt werden:

  • units=metric (Standard) gibt Entfernungen in Kilometern und Metern zurück.
  • units=imperial gibt Entfernungen in Meilen und Fuß zurück.

* Hinweis: Die Festlegung eines Einheitensystems betrifft nur text in den Feldern distance. In den Feldern distance sind zudem Werte (values) enthalten, die stets in Metern angegeben werden.

Distance Matrix-Antworten

Antworten auf Google Maps Distance Matrix API-Abfragen werden in dem Format zurückgegeben, das im Flag output im URL-Anforderungspfad angegeben wurde.

Nachfolgend finden Sie zwei Beispiele für HTTP-Anforderungen, in denen Entfernung und Reisezeit von Vancouver, BC, Kanada, und von Seattle, WA, USA, nach San Francisco, CA, USA, und nach Victoria, BC, Kanada, angefordert werden.

In dieser Anforderung wird die Verwendung des JSON-Flags output veranschaulicht:

https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Victoria+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

In dieser Anforderung wird die Verwendung des XML-Flags output veranschaulicht:

https://maps.googleapis.com/maps/api/distancematrix/xml?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Vancouver+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

Für diese Anforderung werden vier Elemente zurückgegeben, zwei Startpunkte mal zwei Zielorte.

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

Die Ergebnisse werden in Zeilen zurückgegeben, in denen jeweils ein Startpunkt und ein Zielort angezeigt werden.

Probieren Sie es aus! Klicken Sie hier, um die Beispielanforderung in Ihren Browser zu übernehmen. (Wenn Sie zur Auswahl einer Anwendung, mit der die Datei geöffnet werden soll, aufgefordert werden, wählen Sie Ihren Browser oder den von Ihnen bevorzugten Texteditor aus.)

Klicken Sie unten auf die jeweilige Registerkarte, um sich die Beispielantworten in JSON und XML anzusehen.

JSON
{
  "status": "OK",
  "origin_addresses": [ "Vancouver, BC, Canada", "Seattle, État de Washington, États-Unis" ],
  "destination_addresses": [ "San Francisco, Californie, États-Unis", "Victoria, BC, Canada" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 340110,
        "text": "3 jours 22 heures"
      },
      "distance": {
        "value": 1734542,
        "text": "1 735 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 24487,
        "text": "6 heures 48 minutes"
      },
      "distance": {
        "value": 129324,
        "text": "129 km"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 288834,
        "text": "3 jours 8 heures"
      },
      "distance": {
        "value": 1489604,
        "text": "1 490 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 14388,
        "text": "4 heures 0 minutes"
      },
      "distance": {
        "value": 135822,
        "text": "136 km"
      }
    } ]
  } ]
}

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
<?xml version="1.0" encoding="UTF-8"?>
<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Vancouver, BC, Canada</origin_address>
 <origin_address>Seattle, État de Washington, États-Unis</origin_address>
 <destination_address>San Francisco, Californie, États-Unis</destination_address>
 <destination_address>Victoria, BC, Canada</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>340110</value>
    <text>3 jours 22 heures</text>
   </duration>
   <distance>
    <value>1734542</value>
    <text>1 735 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>24487</value>
    <text>6 heures 48 minutes</text>
   </duration>
   <distance>
    <value>129324</value>
    <text>129 km</text>
   </distance>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>288834</value>
    <text>3 jours 8 heures</text>
   </duration>
   <distance>
    <value>1489604</value>
    <text>1 490 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>14388</value>
    <text>4 heures 0 minutes</text>
   </duration>
   <distance>
    <value>135822</value>
    <text>136 km</text>
   </distance>
  </element>
 </row>
</DistanceMatrixResponse>

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.

Distance Matrix-Antwortelemente

Distance Matrix-Antworten enthalten die folgenden Stammelemente:

  • status enthält Metadaten zur Anforderung. Weitere Informationen finden Sie weiter unten unter Statuscodes.
  • origin_addresses enthält ein Array mit Adressen, die von der API von Ihrer ursprünglichen Anforderung zurückgegeben wurden. Diese sind mit geocoder formatiert und gemäß dem Parameter language, der mit der Anforderung übergeben wurde, lokalisiert.
  • destination_addresses enthält ein Array mit Adressen, die von der API von Ihrer ursprünglichen Anforderung zurückgegeben wurden. Wie bei origin_addresses werden auch diese ggf. lokalisiert.
  • rows enthält ein Array von elements, in denen wiederum jeweils die Elemente status, duration und distance enthalten sind.

Statuscodes

Die Felder status im Antwortobjekt enthalten den Status der Anforderung und ggf. auch hilfreiche Debuginformationen. Von Distance Matrix API wird ein allgemeines Statusfeld mit allgemeinen Informationen zur Anforderung sowie ein Statusfeld für jedes Elementfeld mit Informationen über ein bestimmtes Start- und Zielortpaar zurückgegeben.

Allgemeine Statuscodes
  • OK gibt an, dass die Antwort ein gültiges Ergebnis (result) enthält.
  • INVALID_REQUEST gibt an, dass die Anforderung ungültig war.
  • MAX_ELEMENTS_EXCEEDED gibt an, dass die Summe aus Start- und Zielorten das pro Abfrage festgelegte Limit übersteigt.
  • 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 Distance Matrix-Diensts durch Ihre Anwendung verweigert wurde.
  • UNKNOWN_ERROR gibt an, dass eine Distance Matrix-Anforderung aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Möglicherweise ist die Anforderung beim nächsten Versuch erfolgreich.
Statuscodes für Elemente
  • OK gibt an, dass die Antwort ein gültiges Ergebnis (result) enthält.
  • NOT_FOUND gibt an, dass für den Startpunkt und/oder den Zielort dieses Paars kein Geocoding ausgeführt werden konnte.
  • ZERO_RESULTS gibt an, dass zwischen Start- und Zielort keine Route ermittelt werden konnte.

Fehlermeldungen

Bei einem anderen allgemeinen Statuscode als OK wird ggf. im Distance Matrix-Antwortobjekt ein weiteres 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.

Zeilen

Bei der Rückgabe von Google Maps Distance Matrix API-Ergebnissen werden diese im JSON-Array rows platziert. Falls keine Ergebnisse zurückgegeben werden (z. B. wenn Startpunkt und/oder Zielort nicht existieren), wird dennoch ein leeres Array zurückgegeben. XML-Antworten bestehen aus keinem oder mehr Elementen des Typs <row>.

Die Zeilen werden entsprechend den Werten im Parameter origin der Anforderung angeordnet. Jede Zeile entspricht damit einem Startpunkt, und in jedem element der Zeile ist ein Paar aus Startpunkt und destination enthalten.

Jedes Array von row weist einen oder mehrere Einträge des Typs element auf, in dem wiederum Informationen zu einem einzelnen Paar aus Startpunkt und Zielort enthalten sind.

Elemente

Die Informationen über jedes Paar aus Start- und Zielort werden in einem Eintrag des Typs element zurückgegeben. In element sind die folgenden Felder enthalten:

  • status: Eine Liste der möglichen Statuscodes finden Sie unter Statuscodes.
  • duration: Die benötigte Reisezeit für diese Route, angegeben in Sekunden (Wert value) und in text. Der Text wird gemäß dem Parameter language der Abfrage lokalisiert.
  • duration_in_traffic: Die benötigte Reisezeit für diese Route, berechnet 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 Reisedauer wird in Sekunden (Wert value) und in text angegeben. Der Text wird gemäß dem Parameter language der Abfrage lokalisiert. Die Dauer wird nur dann zurückgegeben, wenn alle der folgenden Bedingungen erfüllt sind:

    • Die Anforderung enthält den Parameter departure_time.
    • Die Anforderung enthält einen gültigen API-Schlüssel oder eine gültige Google Maps APIs Premium Plan-Client-ID und Signatur.
    • Für die angeforderte Route sind Informationen über die Verkehrsbedingungen verfügbar.
    • Der Parameter mode ist auf driving festgelegt.
  • distance: Die Gesamtentfernung für diese Route, angegeben in Metern (value) und in text. Für den Textwert wird das Einheitensystem verwendet, das in der ursprünglichen Anforderung im Parameter unit angegeben wurde. Andernfalls wird die Region des Startpunkts herangezogen.
  • fare: Enthält den Gesamtbetrag der Tickets auf dieser Strecke. Diese Eigenschaft wird nur bei Anforderungen für öffentliche Verkehrsmittel und nur für Anbieter von Verkehrsmitteln zurückgegeben, für die Tarifinformationen 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 element mit Tarifinformationen:

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

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 Distance Matrix API
Google Maps Distance Matrix API