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

Für wen ist dieser Leitfaden? Dieser Leitfaden richtet sich an Entwickler, die Dienste für die Reiseplanung und -durchführung mit Lastwagen oder anderen großen Fahrzeugen erstellen. Relevante Anwendungsfälle sind die Berechnung von Reisezeiten und Entfernungen, die Berechnung von voraussichtlichen Ankunftszeiten oder die Generierung von Routen, die von einer Navigationsanwendung verwendet werden.

Inhalt dieses Leitfadens:In diesem Leitfaden wird beschrieben, wie Sie die Routes API mit Large Vehicle Routing verwenden, um Routen, Fahrstrecken, voraussichtliche Fahrzeiten und voraussichtliche Ankunftszeiten abzurufen, die die spezifischen Attribute eines großen Fahrzeugs wie eines Lkw oder Reisebusses berücksichtigen.

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

Lerninhalte

Sie lernen, wie Sie Folgendes tun:

  • Erstellen Sie eine gültige Routinganfrage.
  • Geben Sie ein Fahrzeugprofil für Ihr reales Fahrzeug an, indem Sie Abmessungen, Gewicht und andere Merkmale verwenden.
  • Interpretieren Sie die Antwort, einschließlich des Routen-Tokens und der Flags zur Reisesicherheit.

Vorbereitung

  1. Ihr Google Cloud-Projekt muss erstellt und die Routes API muss aktiviert sein.
  2. Ihr Projekt muss für Large Vehicle Routing bereitgestellt sein. Wenden Sie sich an Ihren Google-Ansprechpartner, um diesen Schritt abzuschließen.

Beschränkungen

Bevor Sie beginnen, sollten Sie sich mit den folgenden Einschränkungen und Anforderungen vertraut machen.

  • Geografische Verfügbarkeit: Die Routenplanung für große Fahrzeuge ist nur in den 48 zusammenhängenden US-Bundesstaaten verfügbar.
  • Die Routenplanung für große Fahrzeuge ist ein Angebot in der Vorschauphase. Fahrer dürfen sich nicht ausschließlich auf die von dieser API zurückgegebenen Routen verlassen, um sicher oder legal zu fahren. Es wird nicht garantiert, dass die Routen für das Fahrzeug geeignet sind. Wenn Fahrer ihnen folgen, können sie Gefahren wie niedrigen Brücken oder Straßen ausgesetzt sein, 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 Sperrzonen führt. In der Antwort der Routes API werden diese Routen im Feld routeRestrictionsPartiallyIgnored deutlich gekennzeichnet. Planen Sie Ihre Route in diesen Fällen sorgfältig, idealerweise mit anderen Quelldaten. Verwenden Sie eine markierte Route nicht als einzige Informationsquelle für die Planung oder Navigation.
  • Nicht unterstützte Funktionen: Wir arbeiten daran, weitere Funktionen in dieses Angebot aufzunehmen. Die Routenplanung für große Fahrzeuge unterstützt jedoch Folgendes nicht:
    • Lkw-Mautpreise
    • Höchstgeschwindigkeit
    • Routen für radioaktive Gefahrstoffe
  • Nutzungslimits:Für alle Anfragen gelten die standardmäßigen Grenzwerte für Abfragen pro Sekunde (QPS).

Lkw-Routenanfrage erstellen

Um eine Lkw-Route zu erhalten, senden Sie eine HTTPS-Anfrage an einen Routes API-Endpunkt mit bestimmten Parametern, die Ihr Fahrzeug beschreiben.

Endpunkte

Für die Lkw-Routenplanung 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 Routen-Polylinie zurück.

Wichtige Parameter für Schlüsselanfragen

Geben Sie im Anfragetext Folgendes an:

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

Fahrzeugprofil angeben

Wenn Sie eine Anfrage senden möchten, müssen Sie einen Anfragetext mit einem vehicleInfo-Objekt angeben, das Ihr Fahrzeug beschreibt. Diese Informationen entsprechen den physischen Details Ihres realen Fahrzeugs. Der Dienst benötigt diese Informationen, um Routen zurückzugeben, bei denen Straßenbeschränkungen basierend auf den Attributen Ihres Fahrzeugs berücksichtigt werden.

Fahrzeugmessungen

Geben Sie das Gewicht des Fahrzeugs in Kilogramm und die Abmessungen des Fahrzeugs in Millimetern an, wie in den Feldnamen angegeben. Die Gesamthöhe sollte beispielsweise in Millimetern (totalHeightMm) angegeben werden. Da Lkw-Abmessungen oft in Fuß oder Metern angegeben werden, kann eine Umrechnung der Einheit erforderlich sein.

Umrechnung von imperialen in metrische Einheiten

Berücksichtigen Sie bei der Umrechnung von imperialen Einheiten immer die Abmessungen Ihres Fahrzeugs sowie die Standardgrößenbeschränkungen für Straßen und Unterführungen. Das kann besonders bei Bruchwerten wichtig sein. Je nach Größe des tatsächlichen Fahrzeugs kann das Aufrunden eines Bruchteils zu einer zu restriktiven Routenführung für das Fahrzeug führen.

Beispiel:

  • Breite: Viele US-Anhänger haben eine Breite von 8 Fuß und 6 Zoll, was 2.590,8 mm entspricht. Wenn Sie auf 2.591 mm aufrunden,wäre das Fahrzeug breiter als 2,59 m und würde auf US-Straßen als übergroßes Fahrzeug eingestuft. Dies würde dann zu einer Route führen, die anhand von deutlich anderen Einschränkungen als beabsichtigt berechnet wurde.
  • Höhe: Eine Route, die unter einer 3,35 m hohen Brücke verläuft, ist nicht für einen typischen Sattelzug mit einer Höhe von 4,11 m geeignet. Kleinere Kastenwagen mit einer Länge von etwa 3 Metern können die Unterführung jedoch passieren. Daher ist es wichtig, die Fahrzeugattribute korrekt 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
      }

vehicleInfo-Objektfelder

In der folgenden Tabelle sind alle Fahrzeug- und Ladungsdefinitionen 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 Gesamtlänge des Fahrzeugs und aller Anhänger. In Millimetern, abgerundet.
totalWeightKg Das zulässige Gesamtgewicht des Fahrzeugs (einschließlich Anhänger und Ladung). In Kilogramm, abgerundet.
totalAxleCount Die Gesamtzahl der Achsen des Fahrzeugs und aller Anhänger. Genau.
trailerInfo (optional) Ein Array von Objekten, eines für jeden Trailer. Bei einem Fahrzeug ohne Anhänger, z. B. einem Kastenwagen, kann dieser Parameter weggelassen werden.
hazardousGoodsTypes (optional) Ein Array, das alle gefährlichen Materialien an Bord angibt. EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

Feldmasken verwenden

Für optimale Ergebnisse sollten Sie den X-Goog-FieldMask-Header in Ihre Anfrage einfügen, um genau die Felder anzugeben, die Sie in der Antwort benötigen. Feldmasken verringern die Latenz und sorgen dafür, dass Sie wichtige Empfehlungsfelder erhalten. Fügen Sie in die Feldmaske immer mindestens routes.travelAdvisory.routeRestrictionsPartiallyIgnored ein, da damit angegeben wird, ob für die Route eine oder mehrere Einschränkungen gelten, die für Ihr Fahrzeug relevant sind.

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

Mautstraßen

Wenn Sie mautfreie Routen bevorzugen möchten, geben Sie avoidTolls im Attribut routeModifiers einer Anfrage an. Weitere Informationen zu Routenmodifikatoren finden Sie unter Zu vermeidende Routenmerkmale angeben.

Wenn Sie avoidTolls angeben, sind gebührenfreie Routen in der Antwort nicht garantiert. In einigen Fällen ist die Nutzung einer mautpflichtigen Straße erforderlich, um vom Start- zum Zielort zu gelangen. Wenn Sie routes.warnings in die Feldmaske Ihrer Routes API-Anfrage einfügen, werden Routen mit Mautstraßen in diesem Feld entsprechend gekennzeichnet.

Beispiel für eine vollständige curl-Anfrage

Hier sehen Sie 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
      }]
    }
  }
}'

computeRoutes-Antwort interpretieren

Bei einer erfolgreichen Anfrage an die Routes API 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 dargestellt werden.
  • Geschätzte Fahrtzeit: routes.duration (in Sekunden). Für die Dauer von Routen für große Fahrzeuge wird ein neues Modell verwendet, das auf den beobachteten Fahrgeschwindigkeiten von tatsächlichen Lkw im Straßennetz basiert. Sie kann auch verwendet werden, um die voraussichtliche Ankunftszeit zu berechnen, indem die geschätzte Fahrtdauer zur voraussichtlichen Abfahrtszeit addiert wird.
  • Gesamtstrecke der Route: routes.distanceMeters (in Metern).
  • Routentoken: routes.routeToken. Dies ist ein intransparentes Token, das die exakt berechnete Route darstellt. Sie übergeben dieses Token an das Navigation SDK, damit dem Fahrer dieselbe lkw-spezifische Route angezeigt wird. Weitere Informationen dazu finden Sie in der Anleitung zum Bereitstellen von Turn-by-Turn-Navigation.

Sicherheitskennzeichnungen für Routen prüfen

Wenn Sie eine Antwort erhalten, sollten Sie als Erstes nach Hinweisen zur Routensicherheit suchen. Wenn eine bereitgestellte 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 Wurde diese Route wegen eines potenziellen Problems gekennzeichnet? zu beantworten.

  • false(oder aus der Antwort weggelassen): Die Route ist nicht gekennzeichnet. Das System hat eine Route gefunden, die den in der Anfrage angegebenen Parametern vollständig entspricht.
  • true: Die Route ist markiert. Das System konnte keine vollständig konforme 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.

Beispiel: computeRoutes-Antwort

Dies ist eine Beispielantwort auf die oben gezeigte Anfrage. Beachten Sie, dass im travelAdvisory-Objekt das Flag routeRestrictionsPartiallyIgnored nicht enthalten ist. Das bedeutet, dass die Route nicht gekennzeichnet ist und davon ausgegangen wird, dass sie vollständig mit dem Fahrzeugprofil übereinstimmt.

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

Matrix mit Lkw-Routen abrufen

Wenn Sie Fahrtzeiten für viele potenzielle Fahrten gleichzeitig berechnen möchten, verwenden Sie den computeRouteMatrix-Endpunkt für die allgemeine Planung, um Fahrtzeiten und Entfernungen zwischen vielen Start- und Zielorten effizient zu vergleichen. Sie können damit beispielsweise den Lkw finden, der einem neuen Abholort am nächsten ist. Sobald Sie den Fahrzeugursprung 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 die vehicleInfo in jedem Ursprungsobjekt an.

Beispielanfrage

{
  "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"
}

Beispielantwort

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

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

Nächste Schritte