Routen und voraussichtliche Ankunftszeiten für große Fahrzeuge generieren

Für wen ist diese Anleitung gedacht? Diese Anleitung richtet sich an Entwickler, die Dienste für die Routenplanung und ‑ausführung mit Lkw oder anderen großen Fahrzeugen erstellen. Relevante Anwendungsfälle sind die Berechnung von Fahrzeiten und Entfernungen, die Berechnung von voraussichtlichen Ankunftszeiten oder die Generierung von Routen, die von einer Navigationsanwendung verwendet werden.

Inhalt dieser Anleitung:In dieser Anleitung wird beschrieben, wie Sie die Routes API mit dem Routing für große Fahrzeuge verwenden, um Routen, Entfernungen, voraussichtliche Fahrzeiten und voraussichtliche Ankunftszeiten anzufordern, die die spezifischen Attribute eines großen Fahrzeugs berücksichtigen, z. B. eines Lkw oder eines Reisebusses.

Informationen zum Ausführen von Berechnungen auf Flottenebene für große Fahrzeuge mit der Route Optimization API finden Sie in der Dokumentation zum Lkw-Routing mit der Route Optimization API.

Lerninhalte

Sie erfahren, wie Sie Folgendes tun:

  • Eine gültige Routinganfrage erstellen.
  • Die Fahrzeuginformationen für Ihr reales Fahrzeug angeben, einschließlich Abmessungen, Gewicht und anderer Merkmale.
  • Die Antwort interpretieren, einschließlich des Routentokens und der Flags für die Verkehrssicherheit.

Vorbereitung

  1. Ihr Google Cloud-Projekt muss erstellt und die Routes API aktiviert sein.
  2. Ihr Projekt muss für das Routing für große Fahrzeuge bereitgestellt sein. Das Routing für große Fahrzeuge ist nur für eine begrenzte Anzahl von Kunden verfügbar. Kontaktieren Sie uns, um Zugriff anzufordern

Beschränkungen

Bevor Sie beginnen, müssen Sie die folgenden Einschränkungen und Anforderungen beachten.

  • Geografische Verfügbarkeit: Das Routing für große Fahrzeuge ist in den zusammenhängenden 48 US-Bundesstaaten (allgemein verfügbar) und Japan (Testphase) verfügbar. Es ist nicht in Alaska, Hawaii oder US-Territorien verfügbar.
  • Fahrerhinweise und Sicherheit. Fahrer dürfen sich nicht ausschließlich auf Routen verlassen, die von dieser API zurückgegeben werden, um sicher oder legal zu sein. Es wird nicht garantiert, dass die Routen für das Fahrzeug geeignet sind. Wenn Fahrer ihnen folgen, können sie Gefahren ausgesetzt sein, z. B. niedrigen Brücken oder Straßen, auf denen große Fahrzeuge verboten sind.
  • Best-Effort-Routen. In einigen Fällen kann die API keine Route finden, die vollständig den Reisebeschränkungen entspricht. Stattdessen wird eine „Best-Effort“-Route zurückgegeben, die möglicherweise durch eingeschränkte Bereiche führt. In der Antwort der Routes API werden diese Routen im Feld routeRestrictionsPartiallyIgnored deutlich gekennzeichnet. Planen Sie in diesen Fällen Ihre Route sorgfältig, idealerweise mit anderen Quelldaten. Verwenden Sie keine gekennzeichnete Route als einzige Informationsquelle für die Planung oder Navigation.
  • Nicht unterstützte Funktionen: Das Routing für große Fahrzeuge unterstützt Folgendes nicht:
    • Lkw-Mautpreise
    • Höchstgeschwindigkeit
    • Routing für radioaktive Gefahrstoffe
  • Nutzungslimits: Für alle Anfragen gelten die Standardlimits für Abfragen pro Sekunde (Queries per Second, QPS).

Anfrage für eine Lkw-Route erstellen

Wenn Sie eine Lkw-Route erhalten möchten, senden Sie eine HTTPS-Anfrage an einen Endpunkt der Routes API mit bestimmten Parametern, die Ihr Fahrzeug beschreiben. Die Konzepte in diesem Abschnitt gelten sowohl für Anfragen für einzelne Routen als auch für Routenmatrixanfragen.

Endpunkte

Für das Lkw-Routing können Sie zwei Endpunkte verwenden:

  • computeRoutes: Berechnet eine einzelne Route zwischen einem Start- und einem Zielort.
  • computeRouteMatrix: Berechnet die Entfernung und Dauer für eine Matrix von Start- und Zielorten, gibt aber keine Routenpolyline zurück.

Wichtige Anfrageparameter

Geben Sie im Anfragetext die folgenden Parameter an, um das Lkw-Routing zu aktivieren:

  • travelMode: Setzen Sie diesen Wert auf TRUCK.
  • routingPreference: Setzen Sie diesen Wert auf TRAFFIC_AWARE_OPTIMAL.
  • routeModifiers: Dieses Objekt enthält das Objekt vehicleInfo, in dem Sie die Attribute Ihres Fahrzeugs definieren. Das Objekt vehicleInfo wird unten ausführlich beschrieben.

Fahrzeugattribute angeben

Um eine Anfrage zu senden, müssen Sie einen Anfragetext mit einem vehicleInfo-Objekt angeben, das Ihr Fahrzeug beschreibt. Diese Informationen können Sie als Spezifikation betrachten, die den physischen Details Ihres realen Fahrzeugs entspricht. Der Dienst benötigt diese Details, um Routen zurückzugeben, die Straßenbeschränkungen basierend auf den Attributen Ihres Fahrzeugs berücksichtigen.

Fahrzeugabmessungen

Geben Sie das Fahrzeuggewicht in Kilogramm und die Fahrzeugabmessungen in Millimetern an, wie in den Feldnamen angegeben. Die Gesamthöhe sollte beispielsweise in Millimetern angegeben werden (totalHeightMm). Da Lkw-Abmessungen häufig in Fuß oder Metern angegeben werden, ist möglicherweise eine Einheitenumrechnung erforderlich.

Umrechnung von imperialen in metrische Einheiten

Bei der Umrechnung von imperialen Einheiten in metrische Einheiten müssen Sie immer die spezifischen Abmessungen Ihres Fahrzeugs sowie die Standardlimits für Straßen- und Unterführungsgrößen berücksichtigen. Dies kann besonders bei Bruchwerten wichtig sein. Je nach Größe des tatsächlichen Fahrzeugs kann das Aufrunden eines Bruchwerts zu einer zu restriktiven Routenplanung für das Fahrzeug führen.

Beispiel:

  • Breite: Viele US-Anhänger haben eine Breite von 8' 6", was 2.590,8 mm entspricht. Wenn Sie auf 2.591 mm aufrunden, wird angegeben, dass das Fahrzeug breiter als 8' 6" ist, wodurch es auf US-Straßen als überbreites Fahrzeug eingestuft wird. Dies würde dann zu einer Route führen, die nach deutlich anderen Einschränkungen berechnet wurde als beabsichtigt.
  • Höhe: Eine Route unter einer 11' hohen Brücke wäre für einen typischen Sattelzug mit einer Höhe von 13,5' nicht geeignet. Kleinere Kastenwagen mit einer Höhe von etwa 10' könnten die Unterführung jedoch passieren. Daher ist es wichtig, die Attribute Ihres Fahrzeugs genau anzugeben.

Ein Diagramm, in dem die Abmessungen eines Lkw den Abmessungen einer Unterführung gegenübergestellt werden

Das folgende Code-Snippet zeigt ein Beispiel für ein vehicleInfo-Objekt:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

Felder des Objekts vehicleInfo

In der folgenden Tabelle sind alle Fahrzeug- und Lastdefinitionen aufgeführt, die Sie mit der Anfrage senden können.

Feld Beschreibung Hinweise / Werte
totalHeightMm Die maximale Höhe des Fahrzeugs. In Millimetern, abgerundet. Weitere Informationen zum Runden finden Sie unter Umrechnung von imperialen in metrische Einheiten.
totalWidthMm Die maximale Breite des Fahrzeugs. In Millimetern, abgerundet.
totalLengthMm Die kombinierte Gesamtlänge des Fahrzeugs und aller Anhänger. In Millimetern, abgerundet.
totalWeightKg Das zulässige Gesamtgewicht des Fahrzeugs (einschließlich Anhänger und Last). In Kilogramm, abgerundet.
totalAxleCount Die Gesamtzahl der Achsen am Fahrzeug und an allen Anhängern. Genau.
trailerInfo (optional) Ein Array von Objekten, eines für jeden Anhänger. Für ein Fahrzeug ohne Anhänger, z. B. einen Kastenwagen, weglassen.
hazardousGoodsTypes (optional) Ein Array, das alle Gefahrstoffe an Bord angibt. EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

Feldmasken verwenden

Um optimale Ergebnisse zu erzielen, fügen Sie den Header X-Goog-FieldMask in Ihre Anfrage ein, um genau die Felder anzugeben, die Sie in der Antwort wünschen. Feldmasken reduzieren die Latenz und sorgen dafür, dass Sie wichtige Warnfelder erhalten. Fügen Sie in der Feldmaske mindestens immer routes.travelAdvisory.routeRestrictionsPartiallyIgnored ein, da dies angibt, ob die Route eine oder mehrere Einschränkungen enthält, die für Ihr Fahrzeug gelten.

Weitere Informationen zu Feldmasken mit der Routes API finden Sie in diesem Artikel.

Mautstraßen

Wenn Sie mautfreie Routen bevorzugen möchten, geben Sie avoidTolls in der Eigenschaft routeModifiers einer Anfrage an. Weitere Informationen zu Routenmodifizierern finden Sie unter Routenfunktionen angeben, die vermieden werden sollen.

Wenn Sie avoidTolls angeben, werden in der Antwort nicht garantiert mautfreie Routen zurückgegeben. In einigen Fällen ist die Nutzung einer Mautstraße erforderlich, um zwischen dem Start- und dem Zielort zu reisen. Wenn Sie routes.warnings in die Feldmaske Ihrer Routes API-Anfrage einfügen, werden Routen mit Mautstraßen in diesem Feld entsprechend gekennzeichnet.

Anderes Routingverhalten

Wenn Sie travelMode auf TRUCK setzen, optimiert die API die Route automatisch für die Manövrierbarkeit großer Fahrzeuge. Generierte Routen vermeiden Wendemanöver und bevorzugen Autobahnen gegenüber kleineren Straßen. Sie müssen keine zusätzlichen Parameter oder Modifizierer festlegen, um dieses Verhalten zu aktivieren.

Einzelne Route mit computeRoutes berechnen

Verwenden Sie den Endpunkt computeRoutes, um eine Lkw-spezifische Route zwischen einem Start- und einem Zielort zu berechnen.

Beispiel für eine computeRoutes-Anfrage

Hier ist eine vollständige curl-Anfrage für einen typischen Sattelzug. Dieses Beispiel enthält den Endpunkt, die Header und den Anfragetext.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Beispiel für eine computeRoutes-Antwort

Dies ist eine Beispielantwort auf die oben gezeigte vorherige Anfrage. Beachten Sie, dass das Flag routeRestrictionsPartiallyIgnored im Objekt travelAdvisory nicht enthalten ist. Das bedeutet, dass die Route nicht gekennzeichnet ist und als vollständig mit den Attributen des Fahrzeugs übereinstimmend gilt.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Antwort von computeRoutes interpretieren

Bei einer erfolgreichen Anfrage an den Endpunkt computeRoutes wird ein JSON-Antwortobjekt mit einer oder mehreren möglichen Routen zurückgegeben.

Wichtige Antwortfelder
  • Codierte Routengeometrie: routes.polyline. Damit kann die Route auf einer Karte gerendert werden.
  • Geschätzte Fahrtzeit: routes.duration (in Sekunden). Für die Fahrtzeit beim Routing für große Fahrzeuge wird ein neues Modell verwendet, das auf den beobachteten Geschwindigkeiten von Lkw im Straßennetz trainiert wurde. Sie kann auch verwendet werden, um die voraussichtliche Ankunftszeit zu berechnen, indem die geschätzte Fahrtzeit zur erwarteten Abfahrtszeit addiert wird.
  • Gesamtstrecke der Route: routes.distanceMeters (in Metern).
  • Routentoken: routes.routeToken. Dies ist ein intransparentes Token, das die genau berechnete Route darstellt. Sie übergeben dieses Token an das Navigation SDK, damit dem Fahrer dieselbe Lkw-spezifische Route angezeigt wird. Weitere Informationen finden Sie in den Navigation SDK-Anleitungen für Android oder iOS.
Auf Flags für die Verkehrssicherheit prüfen

Wenn Sie eine Antwort erhalten, sollten Sie zuerst nach Flags für die Verkehrssicherheit suchen. Wenn eine angegebene Route eine oder mehrere Einschränkungen enthält, die sie für das Fahrzeug ungeeignet machen, ist das Feld travelAdvisory.routeRestrictionsPartiallyIgnored auf true gesetzt.

Dieses Feld dient als Flag, um die Frage zu beantworten, ob diese Route aufgrund eines potenziellen Problems gekennzeichnet ist.

  • false(oder in der Antwort weggelassen): Die Route ist nicht gekennzeichnet. Das System hat eine Route gefunden, die vollständig mit den Parametern übereinstimmt , die Sie in der Anfrage angegeben haben.
  • true: Die Route ist gekennzeichnet. Das System konnte keine vollständig übereinstimmende Route finden und hat eine „Best-Effort“-Route zurückgegeben, die möglicherweise nicht sicher oder legal ist. Diese Route muss mit äußerster Vorsicht verwendet werden.

Matrix von Routen berechnen (computeRouteMatrix)

Verwenden Sie den Endpunkt computeRouteMatrix, um Fahrzeiten und Entfernungen zwischen vielen Start- und Zielorten effizient zu vergleichen. Sie können damit beispielsweise den nächstgelegenen Lkw zu einem neuen Abholort finden. Sobald Sie den Fahrzeugstartort ermittelt haben, den Sie verwenden möchten, können Sie eine computeRoutes-Anfrage senden, um die Routendetails und das Routentoken für das vorgeschlagene Fahrzeug zu erhalten.

Wenn Sie computeRouteMatrix verwenden möchten, geben Sie vehicleInfo in jedem origin-Objekt an, nicht im Stammverzeichnis der Anfrage.

Beispiel für eine computeRouteMatrix-Anfrage

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Beispiel für eine computeRouteMatrix-Antwort

Die Antwort ist ein Array, in dem jedes Objekt die Dauer und distanceMeters für ein Start-Ziel-Paar enthält.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Nächste Schritte