Es kann losgehen!

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

Die Google Maps JavaScript 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 JavaScript API und zugehörige Dienste aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

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.

Erste Schritte

Bevor Sie den Distance Matrix-Dienst in der Google Maps JavaScript API verwenden, müssen Sie zuerst sicherstellen, dass die Google Maps Distance Matrix API in der Google API Console im gleichen Projekt, das Sie für die Google Maps JavaScript API eingerichtet haben, aktiviert ist.

So zeigen Sie die Liste der aktivierten APIs an:

  1. Navigieren Sie zu Google API Console.
  2. Klicken Sie auf die Schaltfläche Select a project, wählen Sie das Projekt aus, das Sie für die Google Maps JavaScript API eingerichtet haben, und klicken Sie auf Open.
  3. Suchen Sie in der Liste der APIs im Dashboard nach Google Maps Distance Matrix API.
  4. Wenn die API in der Liste angezeigt wird, sind Sie startbereit. Wenn die API nicht in der Liste enthalten ist, aktivieren Sie sie:
    1. Wählen Sie oben auf der Seite ENABLE API aus, um den Tab Library anzuzeigen. Alternativ können Sie im Menü auf der linken Seite Library auswählen.
    2. Suchen Sie nach Google Maps Distance Matrix API und wählen Sie den Eintrag dann in der Ergebnisliste aus.
    3. Wählen Sie ENABLE aus. Nachdem der Vorgang abgeschlossen ist, wird die Google Maps Distance Matrix API in der Liste der APIs im Dashboard angezeigt.

Nutzungsbeschränkungen und Richtlinien

Kontingente

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

Hinweis: Jede an den Distance Matrix-Dienst gesendete Abfrage wird durch die Anzahl der zulässigen Elemente begrenzt. Diese Anzahl errechnet sich aus der Anzahl der Startorte multipliziert mit der Anzahl der Zielorte.

Verwendung des Distance Matrix-Diensts mit dem Standard Plan

  • 2.500 kostenlose Elemente pro Tag, berechnet als Summe der clientseitigen und serverseitigen Abfragen; Abrechnung aktivierenaktivieren Sie die Abrechnung, um ein höheres Tageskontingent zu erhalten. Bei maximal 100.000 Elementen pro Tag werden 0,50 USD für 1000 weitere Elemente in Rechnung gestellt.
  • Maximal 25 Startorte oder 25 Zielorte pro Anforderung.
  • Maximal 100 Elemente pro Anforderung.
  • Maximal 100 Elemente pro Sekunde, berechnet als Summe der clientseitigen und serverseitigen Abfragen.

Verwendung des Distance Matrix-Diensts mit dem Premium Plan

  • Übergreifendes kostenloses Tageskontingent von 100.000 Elementen pro 24 Stunden; weitere Anforderungen werden auf die für jeweils ein Jahr erworbenen Maps APIs Credits angerechnet.
  • Maximal 25 Startorte oder 25 Zielorte pro Anforderung.
  • Maximal 625 Elemente pro Anforderung. Hinweis: Anforderungen, die bei mode=driving den optionalen Parameter departure_time verwenden, sind auf 100 Elemente pro Anforderung beschränkt.
  • Unbegrenzt clientseitige Elemente pro Sekunde und Projekt. Beachten Sie, dass die serverseitige API auf 1.000 Elemente pro Sekunde beschränkt ist.

Pro Nutzersitzung wird eine Beschränkung angewendet, unabhängig davon, wie viele Nutzer gemeinsam auf das gleiche Projekt zugreifen.

Die Beschränkung pro Nutzersitzung verhindert, dass clientseitige Dienste für Batchanforderungen genutzt werden. Verwenden Sie für Batchanforderungen den Google Maps Distance Matrix API-Webdienst.

Richtlinien

Die Nutzung des Distance Matrix-Diensts muss im Einklang mit den für die Google Maps Distance Matrix API beschriebenen Richtlinien erfolgen.

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: '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 Adressenzeichenfolgen, google.maps.LatLng-Objekten oder google.maps.Place-Objekten, die als Ausgangspunkte zur Berechnung von Entfernung und Fahrtzeit dienen.
  • destinations (erforderlich) — ein Array mit einer oder mehreren Adressenzeichenfolgen, google.maps.LatLng-Objekten oder google.maps.Place-Objekten, die als Ziele zur Berechnung von Entfernung und Fahrtzeit dienen.
  • 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 TRANSIT ist. Zulässige Werte werden im Abschnitt Optionen für öffentliche Verkehrsmittel erläutert.
  • drivingOptions (optional) gibt Werte an, die nur für Anforderungen gelten, bei denen travelMode gleich 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:

  • BICYCLING: Wegbeschreibungen unter Verwendung von Radwegen und bevorzugten Straßen (derzeit nur in den USA und einigen Orten in Kanada verfügbar).
  • DRIVING (Standardeinstellung): Wegbeschreibungen unter Verwendung des Straßennetzes.
  • 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.
  • 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:
    • 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 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.
  • 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 ausgewählte beste Standardroute übernehmen zu müssen. Dieses Feld kann nur angegeben werden, wenn die Anforderung einen API-Schlüssel enthält. Folgende Werte sind zulässig:
    • FEWER_TRANSFERS gibt an, dass die Route eine möglichst geringe Anzahl von Umstiegen enthalten soll.
    • 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 APIs Premium Plan-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 APIs Premium Plan-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:
    • bestguess (Standardeinstellung) 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.

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

{
  "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 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 (Wert 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 APIs Premium Plan-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 == '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...

Google Maps JavaScript API
Google Maps JavaScript API