„Distance Matrix“-Dienst

Übersicht

Der „Distance Matrix“-Dienst von Google berechnet die Strecke und Reisezeit zwischen mehreren Start- und Zielorten für die vorgegebene Mobilitätsform.

Der Dienst liefert keine detaillierten Routeninformationen. Um Routeninformationen (einschließlich Polylinien und Wegbeschreibungen in Textform) abzurufen, können die einzelnen Start- und Zielorte an den „Directions“-Dienst übergeben werden.

Erste Schritte

Bevor Sie den „Distance Matrix“-Dienst in der Maps JavaScript API verwenden können, müssen Sie die Distance Matrix API in der Google Cloud Console in dem Projekt aktivieren, das Sie für die Maps JavaScript API eingerichtet haben.

So rufen Sie die Liste der aktivierten APIs auf:

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 auf Öffnen.
3. Suchen Sie in der Liste der APIs auf dem Dashboard nach der Distance Matrix API.
4. Wenn die API in der Liste angezeigt wird, müssen Sie nichts weiter tun. Ist die API nicht aufgeführt, aktivieren Sie sie:
   1. Wählen Sie oben auf der Seite API AKTIVIEREN aus, um den Tab Bibliothek aufzurufen. Alternativ können Sie im Menü auf der linken Seite Bibliothek auswählen.
   2. Suchen Sie nach der Distance Matrix API und wählen Sie sie in der Ergebnisliste aus.
   3. Wählen Sie Aktivieren aus. Wenn der Vorgang abgeschlossen ist, wird die Distance Matrix API in der Liste der APIs im Dashboard angezeigt.

Preise und Richtlinien

Preise

Seit 16. Juli 2018 gilt für Maps, Routes und Places ein neues nutzungsorientiertes Preismodell (Pay as you go). Weitere Informationen zu den Preisen und Nutzungslimits für den „Distance Matrix“-Dienst der Maps JavaScript API finden Sie unter Distance Matrix API-Nutzung und -Abrechnung.

Hinweis: Jede Anfrage, die an den „Distance Matrix“-Dienst gesendet wird, ist durch die Anzahl der zulässigen Elemente begrenzt. Diese ergibt sich aus der Anzahl der Startorte multipliziert mit der Anzahl der Zielorte.

Richtlinien

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

„Distance Matrix“-Anfragen

Der Zugriff auf den „Distance Matrix“-Dienst erfolgt asynchron, da die Google Maps API dazu 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 greifen in Ihrem Code über das Konstruktorobjekt google.maps.DistanceMatrixService auf den „Distance Matrix“-Dienst zu. Die Methode DistanceMatrixService.getDistanceMatrix() initiiert eine Anfrage an den „Distance Matrix“-Dienst. Dabei wird ein DistanceMatrixRequest-Objektliteral mit den Startorten, den Zielorten und der Mobilitätsform sowie die Callback-Methode, die beim Erhalten der Antwort ausgeführt werden soll, übergeben.

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 aus einem oder mehreren Adressstrings, google.maps.LatLng-Objekten oder Place-Objekten, auf deren Grundlage Strecke und Reisezeit berechnet werden.
• destinations (erforderlich): Ein Array aus einem oder mehreren Adressstrings, google.maps.LatLng-Objekten oder Place-Objekten, auf deren Grundlage Strecke und Reisezeit berechnet werden.
• travelMode (optional): Die Mobilitätsform, die zur Berechnung der Route verwendet wird. Weitere Informationen finden Sie im Abschnitt Mobilitätsformen.
• transitOptions (optional): Optionen, die nur für Anfragen mit TRANSIT als travelMode gelten. Gültige Werte werden im Abschnitt zu Optionen für öffentliche Verkehrsmittel beschrieben.
• drivingOptions (optional): Gibt Werte an, die nur für Anfragen mit DRIVING als travelMode gelten. Gültige Werte werden im Abschnitt Optionen für Kraftfahrzeuge beschrieben.
• unitSystem (optional): Das Einheitensystem, das für die Anzeige von Strecken verwendet werden soll. Zulässige Werte sind:
  • google.maps.UnitSystem.METRIC (Standard)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (optional): Ist true festgelegt, werden bei der Berechnung von Routen zwischen Start- und Zielorten Autobahnen nach Möglichkeit vermieden.
• avoidTolls (optional): Ist true festgelegt, werden bei der Berechnung von Routen zwischen Start- und Zielorten Mautstraßen nach Möglichkeit vermieden.

Mobilitätsformen

Für die Berechnung von Reisezeiten und Strecken können Sie eine Mobilitätsform angeben. Folgende Mobilitätsformen werden derzeit unterstützt:

• Bei BICYCLING werden Fahrradrouten mit Radwegen und bevorzugten Straßen angefordert (derzeit nur in den USA und einigen kanadischen Städten verfügbar).
• Bei DRIVING (Standardeinstellung) wird eine standardmäßige Wegbeschreibung auf Grundlage des Straßennetzes angefordert.
• Bei TRANSIT werden Routen mit öffentlichen Verkehrsmitteln angefordert. Diese Option kann nur angegeben werden, wenn die Anfrage einen API-Schlüssel enthält. Die verfügbaren Optionen für diese Art von Anfrage finden Sie im Abschnitt Optionen für öffentliche Verkehrsmittel.
• Bei WALKING werden Fußgängerrouten auf Fußgängerwegen und Bürgersteigen (sofern vorhanden) angefordert.

Optionen für öffentliche Verkehrsmittel

Der Dienst für öffentliche Verkehrsmittel ist derzeit experimentell. In dieser Phase gelten Ratenbegrenzungen, um einen Missbrauch der API zu verhindern. Langfristig soll eine Obergrenze für die Gesamtzahl der Anfragen pro Kartenaufruf eingeführt werden, die auf einer fairen Nutzung der API basiert.

Die verfügbaren Optionen für „Distance Matrix“-Anfragen richten sich nach der Mobilitätsform. Bei Anfragen für öffentliche Verkehrsmittel werden die Optionen avoidHighways und avoidTolls ignoriert. Sie können Routenoptionen für öffentliche Verkehrsmittel über das TransitOptions-Objektliteral angeben.

Anfragen für öffentliche Verkehrsmittel sind zeitsensitiv. Berechnungen werden nur für Zeiten in der Zukunft zurückgegeben.

Das TransitOptions-Objektliteral enthält die folgenden Felder:

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

Erläuterungen zu den Feldern:

• arrivalTime (optional) gibt die gewünschte Ankunftszeit als Date-Objekt an. Ist die Ankunftszeit angegeben, wird die Abreisezeit ignoriert.
• departureTime (optional) gibt die gewünschte Startzeit als Date-Objekt an. departureTime wird ignoriert, wenn arrivalTime angegeben ist. Wird kein Wert für departureTime oder arrivalTime angegeben, wird standardmäßig die aktuelle Uhrzeit verwendet.
• modes (optional) ist ein Array aus einem oder mehreren TransitMode-Objektliteralen. Dieses Feld kann nur angegeben werden, wenn die Anfrage einen API-Schlüssel enthält. Jedes TransitMode-Objektliteral gibt ein bevorzugtes Verkehrsmittel an. Folgende Werte sind zulässig:
  • BUS gibt an, dass für die berechnete Route Busse bevorzugt werden sollen.
  • RAIL gibt an, dass für die berechnete Route Züge, Straßenbahnen, Stadtbahnen und U-Bahnen 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.
• routingPreference (optional) gibt Präferenzen für Routen mit öffentlichen Verkehrsmitteln an. Mit dieser Option können Sie die zurückgegebenen Optionen beeinflussen, anstatt die standardmäßige beste Route der API zu verwenden. Dieses Feld kann 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 möglichst wenige Umstiege beinhalten soll.
  • LESS_WALKING gibt an, dass die berechnete Route möglichst wenige Gehstrecken enthalten soll.

Optionen für Kraftfahrzeuge

Mit dem Objekt drivingOptions können Sie eine Startzeit angeben und die beste Route zu Ihrem Ziel unter Berücksichtigung der erwarteten Verkehrslage berechnen lassen. Sie können auch angeben, ob die geschätzte Reisezeit pessimistisch, optimistisch oder die beste Schätzung auf Grundlage historischer und aktueller Verkehrsbedingungen sein soll.

Das Objekt drivingOptions enthält die folgenden Felder:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Erläuterungen zu den Feldern:

• departureTime (erforderlich, damit das Objektliteral drivingOptions gültig ist) gibt die gewünschte Startzeit als Date-Objekt an. Für den Wert muss die aktuelle Zeit oder eine Zeit in der Zukunft angegeben werden. Er darf nicht in der Vergangenheit liegen. (Die API wandelt alle entsprechenden Angaben in UTC um, um eine einheitliche Verarbeitung in allen Zeitzonen sicherzustellen.) Wenn Sie die departureTime in die Anfrage einbeziehen, gibt die API die beste Route angesichts der zu diesem Zeitpunkt zu erwartenden Verkehrslage zurück und schließt die voraussichtliche Reisezeit (duration_in_traffic) in die Antwort ein. Wenn Sie keine Startzeit angeben, drivingOptions also nicht in der Anfrage enthalten ist, wird eine passende Route zurückgegeben, ohne die Verkehrslage zu berücksichtigen.
• trafficModel (optional) 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. Die Standardeinstellung ist best_guess. Folgende Werte sind zulässig:
  • bestguess (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 departureTime rückt.
  • pessimistic gibt an, dass die zurückgegebene duration_in_traffic länger sein sollte als die tatsächliche Reisezeit an den meisten Tagen. An Tagen mit besonders schlechter Verkehrslage kann dieser Wert jedoch überschritten werden.
  • optimistic gibt an, dass die zurückgegebene duration_in_traffic kürzer als die tatsächliche Reisezeit an den meisten Tagen sein sollte. An Tagen mit besonders guter Verkehrslage kann dieser Wert jedoch unterschritten werden.

Hier sehen Sie ein Beispiel für eine DistanceMatrixRequest für eine Kraftfahrzeugroute, einschließlich Startzeit und Verkehrsmodell:

{
  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

Bei erfolgreichen Aufrufen des „Distance Matrix“-Diensts werden ein DistanceMatrixResponse- und ein DistanceMatrixStatus-Objekt zurückgegeben. Sie werden an die Callback-Funktion übergeben, die Sie in der Anfrage definiert haben.

Das DistanceMatrixResponse-Objekt enthält Informationen zur Strecke und Reisezeit für jedes Paar aus Start- und Zielort, 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

Folgende Felder werden in Antworten unterstützt:

• originAddresses ist ein Array aus den Orten, die im Feld origins der „Distance Matrix“-Anfrage übergeben wurden. Die Adressen werden so zurückgegeben, wie sie vom Geocoder formatiert wurden.
• destinationAddresses ist ein Array aus den Orten, die im Feld destinations übergeben wurden. Sie werden so zurückgegeben, wie sie vom Geocoder formatiert wurden.
• rows ist ein Array aus DistanceMatrixResponseRow-Objekten. Dabei entspricht jede Zeile einem Startort.
• elements sind untergeordnete Elemente von rows und entsprechen einem Paar aus dem Startort der Zeile und dem jeweiligen Ziel. Sie enthalten Informationen zu Status, Reisezeit, Strecke und Fahrpreis (sofern verfügbar) für jedes Paar aus Start- und Zielort.
• Jedes 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 als text. Der Textwert wird gemäß dem in der Anfrage angegebenen unitSystem oder alternativ in metrischen Werten formatiert, wenn kein Einheitensystem angegeben wurde.
  • duration_in_traffic: Die Reisezeit für diese Route in Sekunden (Feld value) und als text. Dabei wird die aktuelle Verkehrslage berücksichtigt. Der Textwert wird gemäß dem in der Anfrage angegebenen unitSystem oder alternativ in metrischen Werten formatiert, wenn kein Einheitensystem angegeben wurde. duration_in_traffic wird nur zurückgegeben, wenn Verkehrsdaten verfügbar sind, mode auf driving gesetzt ist und departureTime im Feld distanceMatrixOptions der Anfrage enthalten ist.
  • distance: Die Gesamtstrecke dieser Route in Metern (value) und als text. Der Textwert wird gemäß dem in der Anfrage angegebenen unitSystem oder alternativ in metrischen Werten formatiert, wenn kein Einheitensystem angegeben wurde.
  • fare: Enthält 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. Folgende Informationen werden zurückgegeben:
    • currency: Ein Währungscode nach ISO 4217 für die Währung des Betrags.
    • value: Der Gesamtfahrpreis in der oben angegebenen Währung.

Statuscodes

Die „Distance Matrix“-Antwort enthält einen Statuscode für die gesamte Antwort sowie einen Status für das jeweilige Element.

Statuscodes der Antworten

Folgende Statuscodes für die DistanceMatrixResponse werden im DistanceMatrixStatus-Objekt übergeben:

• OK: Die Anfrage ist gültig. Dieser Status kann auch zurückgegeben werden, wenn zwischen keinem Paar aus Start- und Zielort eine Route gefunden wurde. Informationen zu Status auf Elementebene finden Sie unter Statuscodes der Elemente.
• INVALID_REQUEST: Die Anfrage ist ungültig. Oft liegt das daran, dass Pflichtfelder fehlen. Entsprechende Informationen finden Sie in der Liste der unterstützten Felder oben.
• MAX_ELEMENTS_EXCEEDED: Das Produkt aus Start- und Zielorten überschreitet die Begrenzung pro Anfrage.
• MAX_DIMENSIONS_EXCEEDED: Ihre Anfrage enthielt mehr als 25 Startorte oder mehr als 25 Zielorte.
• OVER_QUERY_LIMIT: Ihre Anwendung hat zu viele Elemente innerhalb des zulässigen Zeitraums angefordert. Die Anfrage sollte erfolgreich sein, wenn Sie lang genug warten und es dann noch einmal versuchen.
• REQUEST_DENIED: Die Verwendung des „Distance Matrix“-Diensts durch Ihre Webseite wurde abgelehnt.
• UNKNOWN_ERROR: Die „Distance Matrix“-Anfrage konnte aufgrund eines Serverfehlers nicht verarbeitet werden. Möglicherweise ist sie beim nächsten Versuch erfolgreich.

Statuscodes der Elemente

Die folgenden Statuscodes werden für bestimmte DistanceMatrixElement-Objekte verwendet:

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

Ergebnisse parsen

Das DistanceMatrixResponse-Objekt enthält eine row für jeden Startort, der in der Anfrage übergeben wurde. Jede Zeile enthält ein element-Feld für jedes Paar aus diesem Startort und den angegebenen Zielorten.

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];
      }
    }
  }
}