Distance Matrix-Dienst

Übersicht

Mit dem Distance Matrix-Dienst von Google werden Entfernungen und Dauer von Reisen zwischen mehreren Start- und Zielorten anhand eines vorgegebenen Verkehrsmittels berechnet.

Von diesem Dienst werden keine detaillierten Routeninformationen geliefert. Diese Routeninformationen, einschließlich Polylinien und Wegbeschreibungen in Textform, können Sie abrufen, indem Sie den gewünschten einzelnen Start- und Zielort an den Directions-Dienst übergeben.

Nutzungsbeschränkungen und Voraussetzungen

Kontingente

Folgende Nutzungsbeschränkungen gelten für den Distance Matrix-Dienst:

  • Maximal 25 Startpunkte oder 25 Zielorte pro Anforderung und:
  • Maximal 100 Elemente (Ausgangsorte mal Zielorte) pro Anforderung.

Anforderungen sind ebenfalls kontingentiert. Werden zu viele Elemente innerhalb einer bestimmten Zeit angefordert, wird ein Antwortcode OVER_QUERY_LIMIT zurückgegeben.

Anzeige einer Google-Karte

Die Nutzung des Distance Matrix-Dienstes muss der Informationsdarstellung auf einer Google-Karte dienen, z. B. um die Start-Ziel-Paare mit einer bestimmten Fahrtzeit zueinander zu ermitteln, bevor diese Ziele aufgerufen und auf einer Karte dargestellt werden. Die Nutzung des Diensts in einer Anwendung, die keine Google-Karte anzeigt, ist untersagt.

Distance Matrix-Anforderungen

Der Zugriff auf den Distance Matrix-Dienst erfolgt asynchron, da dazu der Aufruf eines externen Servers durch Google Maps API erforderlich ist. Aus diesem Grund müssen Sie eine Callbackmethode übergeben, mit der bei Abschluss der Anforderung die Ergebnisse verarbeitet werden sollen.

Sie rufen den Distance Matrix-Dienst von Google Maps API in Ihrem Code über das Objekt google.maps.DistanceMatrixService auf. Mit der Methode GDistanceMatrixService.getDistanceMatrix() wird eine Anforderung an den Distance Matrix-Dienst initiiert und ein Objektliteral DistanceMatrixRequest übergeben, das die Start- und Zielorte, das Verkehrsmittel sowie eine Callbackmethode enthält, die bei Eingang der Antwort ausgeführt wird.

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: google.maps.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 anzeigen (distance-matrix.html)

In DistanceMatrixRequest sind die folgenden Felder enthalten:

  • origins (erforderlich) — ein Array mit einer oder mehreren Adresszeichenfolgen und/oder Objekten vom Typ google.maps.LatLng, zu denen die Entfernung und Zeit berechnet werden.
  • destinations (erforderlich) — ein Array mit einer oder mehreren Adresszeichenfolgen und/oder Objekten vom Typ google.maps.LatLng, von denen Entfernung und Zeit berechnet werden.
  • travelMode (optional) — gibt das Verkehrsmittel an, auf dem die Berechnung der Wegbeschreibung basieren soll. Weitere Informationen finden Sie im Abschnitt Verkehrsmittel.
  • transitOptions (optional) — Optionen, die nur für Anforderungen gelten, bei denen travelMode gleich google.maps.TravelMode.TRANSIT ist. Zulässige Werte werden im Abschnitt Optionen für öffentliche Verkehrsmittel erläutert.
  • drivingOptions (optional): Optionen, die nur für Anforderungen gelten, bei denen travelMode gleich google.maps.TravelMode.DRIVING ist. Zulässige Werte werden im Abschnitt Optionen für Kraftfahrzeuge erläutert.
  • unitSystem (optional) — gibt an, welches Einheitensystem für die Anzeige der Ergebnisse verwendet werden soll. Zulässige Werte sind:
    • google.maps.UnitSystem.METRIC (Standard)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (optional) — ist dieser Wert auf true gesetzt, werden die Routen zwischen Start- und Zielorten so berechnet, dass Autobahnen nach Möglichkeit vermieden werden.
  • avoidTolls (optional) — ist dieser Wert auf true gesetzt, werden die Routen zwischen Punkten so berechnet, dass nach Möglichkeit Straßen ohne Mautgebühren verwendet werden.

Verkehrsmittel

Bei der Berechnung von Zeiten und Entfernungen können Sie das zu verwendende Verkehrsmittel angeben. Folgende Verkehrsmittel werden derzeit unterstützt:

  • google.maps.TravelMode.BICYCLING: Wegbeschreibungen unter Verwendung von Radwegen und bevorzugten Straßen (derzeit nur in den USA und einigen Orten in Kanada verfügbar).
  • google.maps.TravelMode.DRIVING (Standard): Wegbeschreibungen unter Verwendung des Straßennetzes.
  • google.maps.TravelMode.TRANSIT: Wegbeschreibungen unter Verwendung von öffentlichen Verkehrsmitteln. Diese Option kann nur angegeben werden, wenn die Anforderung einen API-Schlüssel enthält. Die verfügbaren Optionen für diese Art der Anforderung finden Sie im Abschnitt Optionen für öffentliche Verkehrsmittel.
  • google.maps.TravelMode.WALKING: Wegbeschreibungen unter Verwendung von Fußwegen (sofern verfügbar).

Optionen für öffentliche Verkehrsmittel

Der Transit-Dienst hat derzeit den Status „Experimental“. In dieser Phase werden wir Kontingentbeschränkungen implementieren, um den Missbrauch der API zu verhindern. Zukünftig werden wir eine Gesamtkapazität der Abfragen pro Karte basierend auf einer fairen Nutzung der API vorgeben.

Die verfügbaren Optionen für eine Distance Matrix-Anforderung kann abhängig vom Verkehrsmittel variieren. Bei Anforderungen für öffentliche Verkehrsmittel werden die Optionen avoidHighways und avoidTolls ignoriert. Sie können spezielle Optionen für die Planung von Routen mit öffentlichen Verkehrsmitteln über das Objektliteral TransitOptions definieren.

Anforderungen von Wegbeschreibungen für öffentliche Verkehrsmittel sind zeitsensitiv. Berechnungen werden nur für Zeiträume in der Zukunft zurückgegeben.

Das Objektliteral TransitOptions enthält folgende Felder:

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

Diese Felder werden nachfolgend erläutert:

  • arrivalTime (optional): Gibt die gewünschte Ankunftszeit als Objekt Date an. Wenn die Ankunftszeit angegeben ist, wird die Abreisezeit ignoriert.
  • departureTime (optional): Gibt die gewünschte Abreisezeit als Objekt Date an. Die Abreisezeit (departureTime) wird ignoriert, wenn arrivalTime angegeben ist. Der Standardwert „jetzt“ (d. h. die aktuelle Zeit) wird verwendet, wenn kein Wert für departureTime oder arrivalTime angegeben ist.
  • modes (optional) ist ein Array mit einem oder mehreren Objektliteralen TransitMode. Dieses Feld kann nur angegeben werden, wenn die Anforderung einen API-Schlüssel enthält. Jedes Feld TransitMode gibt ein oder mehrere bevorzugte öffentliche Verkehrsmittel an. Folgende Werte sind zulässig:
    • google.maps.TransitMode.BUS: gibt an, dass die berechnete Route Busse bevorzugen soll.
    • google.maps.TransitMode.RAIL: gibt an, dass die berechnete Route Züge, Straßenbahnen, Stadtbahnen und U-Bahnen bevorzugen soll.
    • google.maps.TransitMode.SUBWAY: gibt an, dass die berechnete Route die U-Bahn bevorzugen soll.
    • google.maps.TransitMode.TRAIN: gibt an, dass die berechnete Route Züge bevorzugen soll.
    • google.maps.TransitMode.TRAM: gibt an, dass die berechnete Route Straßenbahnen und Stadtbahnen bevorzugen soll.
  • 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 von der API standardmäßig ausgegebene beste Strecke verwenden zu müssen. Dieses Feld kann nur angegeben werden, wenn die Anforderung einen API-Schlüssel enthält. Folgende Werte sind zulässig:
    • google.maps.TransitRoutePreference.FEWER_TRANSFERS: gibt an, dass die berechnete Route eine möglichst geringe Anzahl Umstiege enthalten soll.
    • google.maps.TransitRoutePreference.LESS_WALKING: gibt an, dass die Route möglichst wenige Abschnitte einbeziehen soll, die zu Fuß zurückgelegt werden müssen.

Optionen für Kraftfahrzeuge

Sie können Optionen für die Planung von Routen mit dem Kraftfahrzeug mit dem Objekt DrivingOptions vorgeben. Sie müssen beim Laden der API eine Google Maps API for Work-Client-ID angeben, wenn Sie ein Feld drivingOptions zu DistanceMatrixRequest hinzufügen möchten.

Im Objekt DrivingOptions sind die folgenden Felder enthalten:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Diese Felder werden nachfolgend erläutert:

  • departureTime (erforderlich, damit das Objektliteral drivingOptions zulässig ist): gibt die gewünschte Abreisezeit als Objekt Date an. Dieser Wert muss als aktueller oder zukünftiger Zeitpunkt festgelegt werden. Der Wert kann nicht in der Vergangenheit liegen. (In der API werden alle Datums- und Zeitangaben in UTC umgerechnet, um eine einheitliche Verarbeitung in allen Zeitzonen sicherzustellen.) Wenn Sie departureTime zur Anforderung hinzufügen, wird von der API für Google Maps API for Work-Kunden die beste Route hinsichtlich der erwarteten Verkehrsbedingungen zum jeweiligen Zeitpunkt zurückgegeben. Die vorhergesagte Reisedauer (duration_in_traffic) ist Teil der zurückgegebenen Antwort. Wenn Sie keine Abreisezeit angeben (wenn also drivingOptions nicht in der Antwort enthalten ist), ist die zurückgegebene Route eine generell geeignete Route ohne Berücksichtigung der Verkehrsbedingungen.
  • traffic_model (optional): 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 Standardwert ist best_guess. Folgende Werte sind zulässig:
    • google.maps.TrafficModel.BEST_GUESS (Standard) oder Zeichenfolgenwert best_guess: 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 die Abreisezeit (departureTime) am Zeitpunkt „jetzt“ liegt.
    • google.maps.TrafficModel.PESSIMISTIC oder Zeichenfolgenwert 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.
    • google.maps.TrafficModel.OPTIMISTIC oder Zeichenfolgenwert 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.

Nachfolgend sehen Sie ein Beispiel DistanceMatrixRequest für Routen mit Kraftfahrzeug einschließlich Abreisezeit und Verkehrsmodell:

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

Distance Matrix-Antworten

Bei einem erfolgreichen Aufruf des Distance Matrix-Dienstes werden ein Objekt DistanceMatrixResponse und ein Objekt DistanceMatrixStatus zurückgegeben. Diese werden an die Callbackfunktion übergeben, die Sie in der Anforderung definiert haben.

Das Objekt DistanceMatrixResponse enthält Informationen zu Entfernung und Dauer für jede Kombination aus Start- und Zielort, für die eine Route berechnet werden konnte.

{
  "origin_addresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destination_addresses": [ "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 mit den Standorten, die im Feld origins der Distance Matrix-Anforderung übergeben wurden. Die Adressen werden in der entsprechenden Formatierung durch den Geocoder zurückgegeben.
  • destinationAddresses ist ein Array mit den Standorten, die im Feld destinations der Distance Matrix-Anforderung übergeben wurden, im vom Geocoder zurückgegebenen Format.
  • rows ist ein Array von Objekten DistanceMatrixResponseRow, wobei jede Zeile einem Startort entspricht.
  • elements sind untergeordnete Elemente zu rows und entsprechen der Zuordnung des Startorts der Zeile zum jeweiligen Zielort. Sie enthalten Status, Dauer, Entfernung und Informationen zum Fahrpreis (sofern verfügbar) für jede Kombination von Start-/Zielort.
  • In element sind jeweils 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 (Feld value) und in text. Der Textwert ist gemäß dem in der Anforderung angegebenen Einheitensystem (unitSystem) formatiert (oder in metrischen Einheiten, wenn keine Voreinstellung vorgenommen wurde).
    • duration_in_traffic: Die benötigte Reisezeit für diese Route unter Berücksichtigung der aktuellen Verkehrsbedingungen, angegeben in Sekunden (Feld value) und in text. Der Textwert ist gemäß dem in der Anforderung angegebenen Einheitensystem (unitSystem) formatiert (oder in metrischen Einheiten, wenn keine Voreinstellung vorgenommen wurde). duration_in_traffic wird nur an Google Maps API for Work-Kunden zurückgegeben, wenn Verkehrsdaten zur Verfügung stehen, das Verkehrsmittel (mode) Kraftfahrzeug (driving) angegeben ist und departureTime zum Feld distanceMatrixOptions in der Anforderung hinzugefügt wurde.
    • distance: Die Gesamtentfernung für diese Route, angegeben in Metern (value) und in text. Der Textwert ist gemäß dem in der Anforderung angegebenen Einheitensystem (unitSystem) formatiert (oder in metrischen Einheiten, wenn keine Voreinstellung vorgenommen wurde).
    • 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.

Statuscodes

Die Distance Matrix-Antwort enthält einen Statuscode für die gesamte Antwort sowie Statusangaben zu den einzelnen Elementen.

Antwort-Statuscodes

Statuscodes für DistanceMatrixResponse werden im Objekt DistanceMatrixStatus übergeben. Zu diesen Statuscodes gehören:

  • OK — die Anforderung ist zulässig. Dieser Status kann auch zurückgegeben werden, wenn keine Routen zwischen Start- und Zielorten ermittelt wurden. Statusinformationen auf Element-Ebene finden Sie unter Element-Statuscodes.
  • INVALID_REQUEST — die gestellte Anforderung war ungültig. Dieser Code wird häufig ausgegeben, wenn erforderliche Felder nicht angegeben wurden. Weitere Informationen finden Sie weiter oben in der Liste der unterstützten Typen.
  • MAX_ELEMENTS_EXCEEDED — die Summe aus Start- und Zielorten übersteigt das pro Abfrage festgelegte Limit.
  • MAX_DIMENSIONS_EXCEEDED — Ihre Anforderung enthält mehr als 25 Startorte oder mehr als 25 Zielorte.
  • OVER_QUERY_LIMIT — mit Ihrer Anwendung wurden in einem bestimmten Zeitraum zu viele Anforderungen gestellt. Vermutlich ist die Anforderung erfolgreich, wenn Sie es nach Ablauf eines angemessenen Zeitraums erneut versuchen.
  • REQUEST_DENIED — die Verwendung des Distance Matrix-Diensts durch Ihre Webseite wurde verweigert.
  • UNKNOWN_ERROR — eine Distance Matrix-Anforderung konnte aufgrund eines Serverfehlers nicht verarbeitet werden. Möglicherweise ist die Anforderung beim nächsten Versuch erfolgreich.

Element-Statuscodes

Folgende Statuscodes sind für bestimmte Objekte DistanceMatrixElement möglich:

  • NOT_FOUND — für den Startpunkt und/oder den Zielort dieses Paars konnte kein Geocoding ausgeführt werden.
  • OK — die Antwort enthält ein gültiges Ergebnis.
  • ZERO_RESULTS — zwischen Start- und Zielort konnte keine Route ermittelt werden.

Ergebnisse analysieren

Das Objekt DistanceMatrixResponse enthält eine Zeile (row) für jeden Startpunkt, der mit der Anforderung übergeben wurde. Jede Zeile enthält ein Feld element für jede Kombination dieses Startpunktes mit den angegebenen Zielorten.

function callback(response, status) {
  if (status == google.maps.DistanceMatrixStatus.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];
      }
    }
  }
}

Feedback geben zu...

Diese Seite
Feedback zur Dokumentation
Google Maps JavaScript API
Google Maps JavaScript API
Feedback zum Produkt
Weitere Fragen? Besuchen Sie unsere Supportseite.