Distance Matrix-Dienst

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Übersicht

Der Distance Matrix-Dienst von Google berechnet die Entfernung und Reisedauer zwischen mehreren Start- und Zielorten mit einem bestimmten Reisemodus.

Von diesem Dienst werden keine detaillierten Routeninformationen geliefert. Routeninformationen, einschließlich Polylinien und Routen in Textform, können durch Übergabe des gewünschten einzelnen Start- und Zielorts an den Directions-Dienst abgerufen werden.

Erste Schritte

Bevor Sie den Distance Matrix-Dienst in der Maps JavaScript API verwenden, prüfen Sie zuerst, ob die Distance Matrix API in der Google Cloud Console in dem Projekt aktiviert ist, das Sie für die Maps JavaScript API eingerichtet haben.

So zeigen Sie die Liste der aktivierten APIs an:

  1. Rufen Sie die Google Cloud Console auf.
  2. Klicken Sie auf die Schaltfläche Projekt auswählen, wählen Sie das Projekt aus, das Sie für die Maps JavaScript API eingerichtet haben, und klicken Sie dann auf Öffnen.
  3. Suchen Sie in der Liste der APIs auf dem Dashboard nach Distance Matrix API.
  4. Wenn die API in der Liste angezeigt wird, sind Sie startbereit. Wenn die API nicht aufgeführt ist, aktivieren Sie sie:
    1. Wähle oben auf der Seite API AKTIVIEREN aus, um den Tab Bibliothek aufzurufen. Alternativ kannst du im Menü auf der linken Seite Mediathek auswählen.
    2. Suchen Sie nach der Distance Matrix API und wählen Sie sie dann in der Ergebnisliste aus.
    3. Wähle AKTIVIEREN aus. Wenn der Vorgang abgeschlossen ist, wird die Distance Matrix API in der Liste der APIs im Dashboard angezeigt.

Preise und Richtlinien

Preise

Am 16. Juli 2018 trat für Maps, Routes und Places ein neues „Pay as you go“-Preismodell in Kraft. Weitere Informationen zu den neuen Preis- und Nutzungsbegrenzungen für die Verwendung des JavaScript Distance Matrix-Dienstes finden Sie unter Nutzung und Abrechnung für die Distance Matrix API.

Hinweis: Jede an den Distance Matrix-Dienst gesendete Abfrage ist durch die Anzahl der zulässigen Elemente begrenzt, wobei die Anzahl der Ursprünge × der Anzahl der Ziele die Anzahl der Elemente definiert.

Ratenlimits

Beachten Sie die folgenden Hinweise zu Ratenbegrenzungen für zusätzliche Anfragen:

Das Ratenlimit wird pro Nutzersitzung angewendet, unabhängig davon, wie viele Nutzer dasselbe Projekt verwenden. Beim erstmaligen Laden der API wird Ihnen ein anfängliches Kontingent von Elementen zugewiesen. Wenn Sie dieses Kontingent verwenden, erzwingt die API Ratenbegrenzungen für zusätzliche Anfragen pro Sekunde. Wenn innerhalb eines bestimmten Zeitraums zu viele Anfragen gestellt werden, gibt die API einen OVER_QUERY_LIMIT-Antwortcode zurück.

Das Ratenlimit pro Sitzung verhindert die Verwendung von clientseitigen Diensten für Batchanfragen. Verwenden Sie für Batchanfragen den Distance Matrix API-Webdienst.

Richtlinien

Die Nutzung des Distance Matrix-Diensts muss den Richtlinien für die Distance Matrix API entsprechen.

Distance Matrix-Anforderungen

Der Zugriff auf den Distance Matrix-Dienst erfolgt asynchron, da die Google Maps API einen externen Server aufrufen muss. Aus diesem Grund müssen Sie eine Callback-Methode übergeben, die nach Abschluss der Anfrage ausgeführt wird, um die Ergebnisse zu verarbeiten.

Sie können auf den Distance Matrix-Dienst innerhalb Ihres Codes über das Konstruktorobjekt google.maps.DistanceMatrixService zugreifen. Die Methode DistanceMatrixService.getDistanceMatrix() initiiert eine Anfrage an den Distance Matrix-Dienst und übergibt ihr ein DistanceMatrixRequest-Objektliteral, das die Ursprungsorte, Ziele und den Reisemodus sowie eine Callback-Methode enthält, die nach Erhalt der Antwort ausgeführt werden soll.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Beispiel ansehen

DistanceMatrixRequest enthält die folgenden Felder:

  • origins (erforderlich): ein Array, das einen oder mehrere Adressstrings, google.maps.LatLng-Objekte oder Place-Objekte enthält, von denen ausgehend Entfernung und Zeit berechnet werden
  • destinations (erforderlich): ein Array, das einen oder mehrere Adressstrings, google.maps.LatLng-Objekte oder Place-Objekte enthält, zu denen hin die Entfernung und Zeit berechnet werden
  • travelMode (optional): der Transportmodus, der zur Berechnung der Route verwendet wird. Weitere Informationen findest du im Abschnitt zu Fortbewegungsarten.
  • transitOptions (optional): Optionen, die nur für Anfragen gelten, bei denen travelMode TRANSIT ist. Gültige Werte werden im Abschnitt zu Optionen für öffentliche Verkehrsmittel beschrieben.
  • drivingOptions (optional) gibt Werte an, die nur für Anfragen gelten, bei denen travelMode DRIVING ist. Gültige Werte werden im Abschnitt Optionen für Kraftfahrzeuge beschrieben.
  • unitSystem (optional): das bei der Anzeige der Entfernung zu verwendende Einheitensystem. Zulässige Werte:
    • google.maps.UnitSystem.METRIC (Standard)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (optional): Wenn true ist, werden die Routen zwischen Start- und Zielorten so berechnet, dass Autobahnen wo möglich vermieden werden.
  • avoidTolls (optional): Wenn true, wird die Route zwischen Punkten nach Möglichkeit mit Mautstraßen berechnet.

Verkehrsmittel

Bei der Berechnung von Zeit und Entfernung können Sie die gewünschte Fortbewegungsart angeben. Die folgenden Fortbewegungsarten werden derzeit unterstützt:

  • BICYCLING fordert Fahrradrouten unter Verwendung von Fahrradwegen und bevorzugten Straßen an (derzeit nur in den USA und einigen kanadischen Städten verfügbar).
  • DRIVING (Standard): Gibt die standardmäßigen Anfahrtsbeschreibungen unter Verwendung des Straßennetzes an.
  • TRANSIT fordert Routen mit öffentlichen Verkehrsmitteln an. Diese Option kann nur angegeben werden, wenn die Anfrage einen API-Schlüssel enthält. Informationen zu den verfügbaren Optionen für diese Art von Anfrage finden Sie im Abschnitt Optionen für öffentliche Verkehrsmittel.
  • WALKING fordert Routen mit Fußgängerwegen und Bürgersteigen an (sofern verfügbar).

Optionen für öffentliche Verkehrsmittel

Der Dienst für öffentliche Verkehrsmittel ist derzeit experimentell. In dieser Phase implementieren wir Ratenbegrenzungen, um API-Missbrauch zu verhindern. Letztendlich wird eine Obergrenze für die Gesamtzahl der Abfragen pro Kartenaufruf auf der Grundlage der fairen Nutzung der API durchgesetzt.

Die verfügbaren Optionen für eine Distance Matrix-Anforderung kann abhängig vom Verkehrsmittel variieren. Bei Anfragen für öffentliche Verkehrsmittel werden die Optionen avoidHighways und avoidTolls ignoriert. Mit dem Objektliteral TransitOptions können Sie routenspezifische Routingoptionen angeben.

Anforderungen von Wegbeschreibungen für öffentliche Verkehrsmittel sind zeitsensitiv. Berechnungen werden nur für zukünftige Zeiten zurückgegeben.

Das Objektliteral TransitOptions enthält die folgenden Felder:

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

Diese Felder werden im Folgenden beschrieben:

  • arrivalTime (optional) gibt die gewünschte Ankunftszeit als Date-Objekt an. Wenn die Ankunftszeit angegeben ist, wird die Abfahrtszeit ignoriert.
  • departureTime (optional) gibt die gewünschte Abfahrtszeit als Date-Objekt an. departureTime wird ignoriert, wenn arrivalTime angegeben ist. Wenn kein Wert für departureTime oder arrivalTime angegeben ist, wird standardmäßig die aktuelle Uhrzeit verwendet.
  • modes (optional) ist ein Array, das ein oder mehrere TransitMode-Objektliterale enthält. Dieses Feld darf nur enthalten sein, wenn die Anfrage einen API-Schlüssel enthält. Für jede TransitMode wird ein bevorzugtes Verkehrsmittel angegeben. Folgende Werte sind zulässig:
    • BUS gibt an, dass die berechnete Route mit dem Bus bevorzugt werden soll.
    • RAIL gibt an, dass für die berechnete Route Züge, Straßenbahnen, Stadtbahnen und U-Bahnen bevorzugt werden sollen.
    • SUBWAY gibt an, dass die berechnete Route mit der U-Bahn bevorzugt werden soll.
    • TRAIN gibt an, dass die berechnete Route mit dem Zug bevorzugt werden soll.
    • TRAM gibt an, dass für die berechnete Route Straßenbahnen und Stadtbahnen bevorzugt werden sollen.
  • routingPreference (optional) gibt Einstellungen für Routen mit öffentlichen Verkehrsmitteln an. Mit dieser Option können Sie die zurückgegebenen Optionen anpassen, anstatt die von der API ausgewählte beste Standardroute zu akzeptieren. Dieses Feld darf nur angegeben werden, wenn die Anfrage einen API-Schlüssel enthält. Folgende Werte sind zulässig:
    • FEWER_TRANSFERS gibt an, dass die berechnete Route eine begrenzte Anzahl von Umstiegen vorziehen soll.
    • LESS_WALKING gibt an, dass für die berechnete Route nur wenige Fußwege bevorzugt werden sollen.

Optionen für Kraftfahrzeuge

Mit dem Objekt drivingOptions geben Sie die Abfahrtszeit an, um die beste Route zu Ihrem Ziel unter Berücksichtigung der erwarteten Verkehrsbedingungen zu berechnen. Du kannst auch angeben, ob die geschätzte Zeit für den Traffic pessimistisch, optimistisch oder anhand der bisherigen Verkehrslage und der aktuellen Verkehrslage optimal sein soll.

Das Objekt drivingOptions enthält die folgenden Felder:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Diese Felder werden im Folgenden beschrieben:

  • departureTime (erforderlich, damit das Objektliteral drivingOptions gültig ist) gibt die gewünschte Abfahrtszeit als Date-Objekt an. Als Wert muss die aktuelle oder eine Zeit in der Zukunft festgelegt werden. Er darf nicht in der Vergangenheit liegen. Die API wandelt alle Datumsangaben in UTC um, um eine konsistente Verarbeitung in allen Zeitzonen sicherzustellen. Wenn du departureTime in die Anfrage aufnimmst, gibt die API je nach erwarteter Verkehrslage die beste Route zurück und schließt die vorhergesagte Zeit im Traffic (duration_in_traffic) in die Antwort ein. Wenn Sie keine Abfahrtszeit angeben, d. h. wenn die Anfrage drivingOptions nicht enthält, ist die zurückgegebene Route im Allgemeinen eine gute Route, ohne die Verkehrslage zu berücksichtigen.

    Hinweis: Wenn keine Abfahrtszeit angegeben ist, basieren die Auswahl der Route und die Dauer 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, aktualisierten durchschnittlichen Verkehrsverhältnissen und der Verteilung der Dienste ändern. Außerdem können die Ergebnisse für die Äquivalente von Routen in nahezu gleicher Häufigkeit oder Häufigkeit variieren.

  • trafficModel (optional) gibt die Annahmen an, die bei der Berechnung der Zeit im Traffic verwendet werden sollen. Diese Einstellung wirkt sich auf den Wert aus, der im Feld duration_in_traffic in der Antwort zurückgegeben wird. Sie enthält die vorhergesagte Zeit im Traffic, basierend auf den bisherigen Durchschnittswerten. Die Standardeinstellung ist best_guess. Folgende Werte sind zulässig:
    • bestguess (Standard) gibt an, dass die zurückgegebene duration_in_traffic die beste Schätzung der Fahrzeit sein soll, wenn man die bisherigen Verkehrsverhältnisse und die aktuelle Verkehrslage kennt. Je näher der departureTime, desto näher ist auch der Live-Verkehr.
    • pessimistic gibt an, dass der zurückgegebene duration_in_traffic an den meisten Tagen länger als die tatsächliche Reisezeit sein sollte. Gelegentlich können Tage mit besonders schlechten Verkehrsdaten diesen Wert jedoch überschreiten.
    • optimistic gibt an, dass der zurückgegebene duration_in_traffic an den meisten Tagen kürzer als die tatsächliche Reisezeit sein sollte. Gelegentlich können Tage mit besonders guter Verkehrslage jedoch schneller als dieser Wert sein.

Hier ein Beispiel für ein DistanceMatrixRequest für Routen mit Abfahrt und Verkehrslage:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Distance Matrix-Antworten

Ein erfolgreicher Aufruf an den Distance Matrix-Dienst gibt ein DistanceMatrixResponse- und ein DistanceMatrixStatus-Objekt zurück. Diese werden an die in der Anfrage angegebene Callback-Funktion übergeben.

Das DistanceMatrixResponse-Objekt enthält Informationen zu Entfernung und Dauer für jedes Start-/Zielpaar, für das eine Route berechnet werden kann.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Distance Matrix-Ergebnisse

Die in einer Antwort unterstützten Felder sind nachfolgend erläutert:

  • originAddresses ist ein Array, das die im Feld origins der Distance Matrix-Anfrage übergebenen Standorte enthält. Die Adressen werden in der entsprechenden Formatierung durch den Geocoder zurückgegeben.
  • destinationAddresses ist ein Array, das die im Feld destinations übergebenen Standorte in dem vom Geocoder zurückgegebenen Format enthält.
  • rows ist ein Array von DistanceMatrixResponseRow-Objekten, wobei jede Zeile einem Ursprung entspricht.
  • elements sind untergeordnete Elemente von rows und entsprechen einer Kombination aus dem Ursprungsort der Zeile mit den einzelnen Zielen. Sie enthalten Status, Dauer, Entfernung und Tarifinformationen (falls verfügbar) für jedes Start-/Zielpaar.
  • Jeder element enthält die folgenden Felder:
    • status: Unter Statuscodes finden Sie eine Liste der möglichen Statuscodes.
    • duration: Die Reisezeit in Sekunden (Feld value) und text. Der Textwert ist gemäß dem in der Anfrage angegebenen unitSystem formatiert (oder in metrischen Werten, wenn keine Einstellung angegeben wurde).
    • duration_in_traffic: Die Reisedauer (unter Verwendung des aktuellen Verkehrsaufkommens, angegeben in value) und text. Der Textwert ist gemäß dem in der Anfrage angegebenen unitSystem formatiert (oder in metrischen Werten, wenn keine Einstellung angegeben wurde). duration_in_traffic wird nur für Kunden mit Google Maps Platform-Premiumoption zurückgegeben, für die Daten zur Verkehrslage verfügbar sind, für die mode der Wert driving und departureTime als Teil des Felds distanceMatrixOptions in der Anfrage angegeben ist.
    • distance: Die Gesamtentfernung dieser Route in Metern (value) und als text ausgedrückt. Der Textwert ist gemäß dem in der Anfrage angegebenen unitSystem formatiert (oder in metrischen Werten, wenn keine Einstellung angegeben wurde).
    • fare: Enthält den Gesamtpreis (d. h. die gesamten Ticketkosten) dieser Route. Dieses Attribut wird nur für Fahrkarten für öffentliche Verkehrsmittel und für Verkehrsunternehmen zurückgegeben, für die Preisinformationen verfügbar sind. Dazu gehören:
      • currency: Ein Währungscode nach ISO 4217, der die Währung angibt, in der der Betrag ausgedrückt wird.
      • value: Der Gesamtbetrag des Preises in der oben angegebenen Währung.

Statuscodes

Die Distance Matrix-Antwort enthält einen Statuscode für die Antwort als Ganzes sowie einen Status für jedes Element.

Antwort-Statuscodes

Statuscodes, die für DistanceMatrixResponse gelten, werden im DistanceMatrixStatus-Objekt übergeben und umfassen Folgendes:

  • OK: Die Anfrage ist gültig. Dieser Status kann zurückgegeben werden, auch wenn keine Routen zwischen einem der Start- und Zielorte gefunden wurden. Unter Statuscodes der Elemente finden Sie die Statusinformationen auf Elementebene.
  • INVALID_REQUEST: Die eingegebene Anfrage war ungültig. Dieser Code wird häufig ausgegeben, wenn erforderliche Felder nicht angegeben wurden. Weitere Informationen finden Sie oben in der Liste der unterstützten Felder.
  • MAX_ELEMENTS_EXCEEDED: Das Produkt von Ursprüngen und Zielen überschreitet das Limit pro Abfrage.
  • MAX_DIMENSIONS_EXCEEDED: Deine Anfrage enthielt mehr als 25 Startorte oder mehr als 25 Ziele.
  • OVER_QUERY_LIMIT: Deine Anwendung hat zu viele Elemente innerhalb des zulässigen Zeitraums angefordert. Die Anfrage sollte erfolgreich sein, wenn Sie es nach einiger Zeit noch einmal versuchen.
  • REQUEST_DENIED: Der Dienst hat die Verwendung des Distance Matrix-Dienstes durch Ihre Webseite abgelehnt.
  • UNKNOWN_ERROR: Eine Distance Matrix-Anfrage konnte aufgrund eines Serverfehlers nicht verarbeitet werden. Die Anfrage ist möglicherweise erfolgreich, wenn Sie es noch einmal versuchen.

Element-Statuscodes

Die folgenden Statuscodes gelten für bestimmte DistanceMatrixElement-Objekte:

  • NOT_FOUND: Der Ursprung und/oder das Ziel dieses Paars konnten nicht geocodiert werden.
  • OK: Die Antwort enthält ein gültiges Ergebnis.
  • ZERO_RESULTS: Es wurde keine Route zwischen Start- und Zielort gefunden.

Ergebnisse analysieren

Das DistanceMatrixResponse-Objekt enthält eine row für jeden Ursprung, der in der Anfrage übergeben wurde. Jede Zeile enthält das Feld element für jedes Paar dieses Ursprungs mit den angegebenen Zielen.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}