Entfernungsmatrix-API | Reisezeit und Entfernung

Was können Sie mit der Distance Matrix API machen?

Warum Distance Matrix API verwenden?

So verwenden Sie die Distance Matrix API

Parameter anfordern

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=<origin_location_1|origin_location_2|...|origin_location_n>&destinations=<destination_location_1|destination_location_2|...|destination_location_n>&key=<your_access_token>

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

Erforderliche Parameter

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom&destinations=St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom&key=<your_access_token>

{
    "destination_addresses": [
        "St John's Church, North End Rd, London SW6 1PB, United Kingdom"
    ],
    "origin_addresses": [
        "Westminster Abbey, 20 Deans Yd, London SW1P 3PA, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.3 km",
                        "value": 7346
                    },
                    "duration": {
                        "text": "23 mins",
                        "value": 1401
                    },
                    "origin": "Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom",
                    "destination": "St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Optionale Parameter

• Modus (standardmäßig Fahren) — gibt das Transportmittel an, das bei der Berechnung der Entfernung verwendet werden soll. Gültige Werte und andere Anforderungsdetails sind in der Reisemodi Abschnitt dieses Dokuments.
• Sprache — eine Sprache, die verwendet wird, um Ergebnisse zurückzugeben.
  
  • 
    Sehen Sie sich die Liste der unterstützten Sprachen an.
    
  • 
    Wenn keine Sprache angegeben wird, versucht die API, die bevorzugte Sprache zu verwenden, wie im Accept-Language-Header angegeben, oder die Muttersprache der Domain, von der die Anfrage gesendet wird.
    
  • 
    Die API gibt ihr Bestes, um eine Straßenadresse bereitzustellen, die sowohl für den Benutzer als auch für die Einheimischen lesbar ist. Um dieses Ziel zu erreichen, gibt sie Straßenadressen in der Landessprache zurück, die bei Bedarf in eine vom Benutzer lesbare Schrift transliteriert werden, wobei die bevorzugte Sprache eingehalten wird. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die aus der ersten Komponente ausgewählt wurde.
    
  • 
    Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API den am ehesten passenden Namen.
    
  • 
    Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnismenge, die die API zurückgibt, und auf die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. die Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sein können, in einer anderen jedoch nicht. Zum Beispiel sind utca und tér Synonyme für Straße auf Ungarisch.
    

• vermeiden — führt Einschränkungen für die Route ein. Gültige Werte sind angegeben im Einschränkungen Abschnitt dieses Dokuments. Es kann nur eine Einschränkung angegeben werden.
• Einheiten — gibt das Einheitensystem an, das beim Ausdrücken von Entfernungen als Text verwendet werden soll. Sehen Sie sich die Einheitensysteme Abschnitt dieses Dokuments für weitere Informationen.
  
• arrival_time — gibt die gewünschte Ankunftszeit für Transitanfragen in Sekunden seit Mitternacht, 1. Januar 1970, UTC an. Sie können entweder departure_time oder arrival_time angeben, aber nicht beide. Beachten Sie, dass arrival_time als Ganzzahl angegeben werden muss.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&arrival_time=now&transit_mode=bus&mode=transit&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "166.4 km",
                        "value": 166409
                    },
                    "duration": {
                        "text": "4 hour 2 mins",
                        "value": 14524
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• departure_time — eine gewünschte Abfahrtszeit. Sie können die Uhrzeit als Ganzzahl in Sekunden seit Mitternacht, 1. Januar 1970, UTC angeben. Alternativ können Sie den Wert now angeben, wodurch die Abfahrtszeit auf die aktuelle Uhrzeit (auf die nächste Sekunde genau) gesetzt wird. Die Abflugzeit muss auf die aktuelle Uhrzeit oder einen Zeitpunkt in der Zukunft gesetzt werden. Es kann nicht in der Vergangenheit sein. Die Ergebnisse für eine bestimmte Anfrage können im Laufe der Zeit aufgrund der Änderungen im Straßennetz, der aktualisierten durchschnittlichen Verkehrsbedingungen und der verteilten Art des Dienstes variieren. Die Ergebnisse können auch zwischen nahezu gleichwertigen Strecken zu jeder Zeit oder Häufigkeit variieren. Die Abfahrtszeit kann in zwei Fällen angegeben werden:
  
  • 
    Für Anfragen, bei denen der Reisemodus Transit ist: Sie können optional zwischen departure_time oder arrival_time angeben. Wenn keine der beiden Zeiten angegeben ist, ist die Abflugzeit standardmäßig auf jetzt gesetzt (das heißt, die Abfahrtszeit entspricht standardmäßig der aktuellen Uhrzeit).
    
  • 
    Für Anfragen, bei denen der Reisemodus fährt: Sie können die Abfahrtszeit angeben, um eine Route und die Reisedauer (Antwortfeld: duration_in_traffic) zu erhalten, die die Verkehrsbedingungen berücksichtigen. Die Abflugzeit muss auf die aktuelle Uhrzeit oder einen Zeitpunkt in der Zukunft gesetzt werden. Es kann nicht in der Vergangenheit sein.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• traffic_model (standardmäßig best_guess) — gibt die Annahmen an, die bei der Berechnung der Zeit im Verkehr verwendet werden sollen. Diese Einstellung wirkt sich auf den Wert aus, der in der Antwort im Feld duration_in_traffic zurückgegeben wird. Dieses Feld enthält die auf historischen Durchschnittswerten basierende prognostizierte Verkehrszeit. Der Parameter traffic_model darf nur für Anfragen angegeben werden, bei denen der Reisemodus Fahren lautet und bei denen die Anforderung eine departure_time enthält. Die verfügbaren Werte für diesen Parameter sind:
  
  • 
    best_guess (Standard) gibt an, dass die zurückgegebene duration_in_traffic die beste Schätzung der Reisezeit sein sollte, wenn man bedenkt, was sowohl über historische Verkehrsbedingungen als auch über Live-Verkehr bekannt ist. Der aktuelle Verkehr wird umso wichtiger, je näher die Abfahrtszeit an der aktuellen Uhrzeit liegt.
    
  • 
    pessimistisch bedeutet, dass die zurückgegebene duration_in_traffic an den meisten Tagen länger als die tatsächliche Reisezeit sein sollte, obwohl gelegentlich Tage mit besonders schlechten Verkehrsbedingungen diesen Wert überschreiten können. Wirkt sich auf das Feld in der distance_in_traffic_model-Antwort aus und gibt die kürzeste Route zurück.
    
  • 
    optimistisch bedeutet, dass die zurückgegebene duration_in_traffic an den meisten Tagen kürzer als die tatsächliche Reisezeit sein sollte, obwohl gelegentlich Tage mit besonders guten Verkehrsbedingungen schneller als dieser Wert sein können. Wirkt sich auf das Feld in der distance_in_traffic_model-Antwort aus und gibt die kürzeste Route zurück.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&traffic_model=pessimistic&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "4 hour 0 mins",
                        "value": 14400
                    },
                    "distance_in_traffic_model": {
                        "text": "118 miles",
                        "value": 189274
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• transit_mode — gibt einen oder mehrere bevorzugte Transitmodi an. Dieser Parameter darf nur für Anfragen angegeben werden, bei denen der Transitmodus ist. Der Parameter unterstützt die folgenden Argumente:
  
  • 
    Bus gibt an, dass die berechnete Route die Fahrt mit dem Bus bevorzugen sollte.
    
  • 
    U-Bahn gibt an, dass die berechnete Route eine Fahrt mit der U-Bahn bevorzugen sollte.
    
  • 
    Zug gibt an, dass die berechnete Route eine Reise mit dem Zug bevorzugen sollte.
    
  • 
    tram gibt an, dass die berechnete Route eine Fahrt mit Straßenbahn und Stadtbahn bevorzugen sollte.
    
  • 
    Bahn gibt an, dass die berechnete Route Reisen mit Zug, Straßenbahn, Stadtbahn und U-Bahn bevorzugen sollte. Dies entspricht transit_mode=train|tram|subway.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&transit_mode=bus|train|tram|subway&mode=transit&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Reisemodi

• Fahren (Standard) gibt die Entfernungsberechnung mithilfe des Straßennetzes an.
  
• Gehen fordert die Berechnung der Entfernung für das Gehen über Fußgängerwege und Bürgersteige an (sofern verfügbar).
  
• Radfahren fordert die Berechnung der Entfernung für das Radfahren über Fahrradwege und bevorzugte Straßen an (sofern verfügbar).
  
• Transit fordert die Berechnung der Entfernung über öffentliche Verkehrswege an (sofern verfügbar). Wenn Sie den Modus auf Transit einstellen, müssen Sie entweder eine Abflugzeit oder eine Ankunftszeit angeben. Wenn keine der beiden Zeiten angegeben ist, ist die Abflugzeit standardmäßig auf jetzt gesetzt (das heißt, die Abfahrtszeit entspricht standardmäßig der aktuellen Uhrzeit). Sie müssen auch einen transit_mode angeben.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=walking&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "5.7 km",
                        "value": 5699
                    },
                    "duration": {
                        "text": "1 hour 12 mins",
                        "value": 4379
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Informationen zum Verkehr

• Der Reisemodusparameter ist Fahren oder er ist nicht angegeben (Fahren ist der Standardreisemodus).
  
• Die Anfrage enthält einen gültigen departure_time-Parameter. Die Abflugzeit kann auf die aktuelle Uhrzeit oder eine andere Uhrzeit gesetzt werden.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "23 mins",
                        "value": 1395
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Einschränkungen

• avoid=tolls
  
• avoid=highways
  
• avoid=ferries
  
• avoid=indoor
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&avoid=ferries&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Einheitensysteme

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

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&departure_time=now&units=imperial&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "4.7 mi",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Beispiel für eine Antwort

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Reaktionselemente der Entfernungsmatrix

• status enthält Metadaten zur Anfrage. Siehe Statuscodes unten.
  
• origin_addresses enthält ein Array von Adressen, wie sie von der API aus Ihrer ursprünglichen Anfrage zurückgegeben wurden. Diese werden vom Geocoder formatiert und entsprechend dem mit der Anfrage übergebenen Sprachparameter lokalisiert.
  
• destination_addresses enthält ein Array von Adressen, die von der API aus Ihrer ersten Anfrage zurückgegeben wurden. Wie bei origin_addresses sind diese gegebenenfalls lokalisiert.
  
• Zeilen enthalten ein Array von Elementen, die wiederum Status-, Dauer- und Entfernungselemente enthalten.
  

Statuscodes

Statuscodes der obersten Ebene

• OK bedeutet, dass die Antwort ein gültiges Ergebnis enthält.
• INVALID_REQUEST gibt an, dass die angegebene Anfrage ungültig war.
• MAX_ELEMENTS_EXCEEDED gibt an, dass das Produkt aus Ursprung und Ziel das Limit pro Abfrage überschreitet.
• OVER_DAILY_LIMIT gibt einen der folgenden Werte an:
  
  • 
    Der API-Schlüssel fehlt oder ist ungültig.
    
  • 
    Die Abrechnung wurde für Ihr Konto nicht aktiviert.
    
  • 
    Eine selbst auferlegte Nutzungsobergrenze wurde überschritten.
    
  • 
    Die angegebene Zahlungsmethode ist nicht mehr gültig (z. B. ist eine Kreditkarte abgelaufen).
    
• OVER_QUERY_LIMIT gibt an, dass der Dienst innerhalb des zulässigen Zeitraums zu viele Anfragen von Ihrer Anwendung erhalten hat.
• REQUEST_DENIED gibt an, dass der Dienst die Verwendung des Distance Matrix-Dienstes durch Ihre Anwendung verweigert hat.
• UNKNOWN_ERROR gibt an, dass eine Entfernungsmatrix-Anfrage aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Die Anfrage kann erfolgreich sein, wenn Sie es erneut versuchen.

Statuscodes auf Elementebene

• OK gibt die Antwort an und enthält ein gültiges Ergebnis.
  
• NOT_FOUND gibt an, dass der Ursprung und/oder das Ziel dieser Paarung nicht geokodiert werden konnten.
  
• ZERO_RESULTS gibt an, dass keine Route zwischen dem Start- und dem Zielort gefunden werden konnte.
  
• MAX_ROUTE_LENGTH_EXCEEDED gibt an, dass die angeforderte Route zu lang ist und nicht verarbeitet werden kann.
  

Fehlermeldungen

Reihen

Elemente

• Status: Siehe Statuscodes für eine Liste möglicher Statuscodes.
  
• Dauer: Die Dauer, die benötigt wird, um diese Route zurückzulegen, ausgedrückt in Sekunden (das Wertfeld) und als Text.
  
• duration_in_traffic: Die Dauer, die benötigt wird, um diese Route zurückzulegen, basierend auf aktuellen und historischen Verkehrsbedingungen.
  
• Entfernung: Die Gesamtstrecke dieser Route, ausgedrückt in Metern (Wert) und als Text. Der Textwert verwendet das Einheitensystem, das mit dem Einheitenparameter der ursprünglichen Anfrage angegeben wurde, oder die Region des Ursprungs.
  
• distance_in_traffic_model: Die kürzeste Entfernung, die benötigt wird, um diese Route zurückzulegen, basierend auf aktuellen und historischen Verkehrsbedingungen.