Route planen

Manchmal möchten Sie vielleicht die Route planen, die Ihre App den Nutzern vorschlägt. Mit einem Routentoken aus der Routes API oder der Route Optimization API können Sie zwei Dinge für Ihre geplante Route angeben:

• Eine Polylinie für die Route

• Ihre Routenziele

Hier einige Beispiele für Routingziele:

• Lieferzeit minimieren: Ein Unternehmen, das Lebensmittel liefert, möchte möglicherweise die Lieferzeit minimieren.

• Reisedauer oder Kraftstoffverbrauch minimieren: Ein Logistikunternehmen möchte die Effizienz seiner Fahrer verbessern und die Kraftstoffkosten senken.

• Zeit bis zum Ziel minimieren: Bei einem Service-Dispatch-Vorgang soll möglicherweise die Zeit minimiert werden, die Operatoren benötigen, um zu einer Auftragsanfrage zu gelangen.

• Kosten senken und Sicherheit verbessern: Ein Fahrdienstanbieter möchte möglicherweise eine Route finden, die für die Fahrgäste günstiger ist und aus Sicherheitsgründen bestimmte Bereiche meidet.

Wichtig : Die von den Fahrern zurückgelegte Route kann von der geplanten Route abweichen. Die Route kann sich während der Fahrt ändern, wenn sich die Verkehrs- oder Straßenverhältnisse ändern, das Fahrzeug die geplante Route verlässt oder zu einer schnelleren Route gewechselt wird. Wenn das Navigation SDK eine neue Route berechnet, werden die im Routentoken festgelegten Routingoptionen verwendet, z. B. das Vermeiden von Mautgebühren.

Weitere Informationen zum Planen einer Route mit einem Routentoken finden Sie unter Routentoken abrufen in der Routes API und unter Übergangspolylinien und Routentokens in der Route Optimization API.

Vorteile von Routentokens für Routenziele

Mit einem Routentoken aus der Routes API oder der Route Optimization API haben Sie mehr Kontrolle über die bereitgestellte Route:

• Planen Sie eine Route im Voraus, die vom Navigation SDK verwendet werden soll.

• Die beste Route für das Navigation SDK auswählen Wenn Sie beim Generieren von Routen in der Routes API Routen-Tokens anfordern, erhalten Sie für jede generierte Route ein Routen-Token. Sie können dann das Token für die gewünschte Route auswählen, wenn Sie es an das Navigation SDK übergeben.

• Schätzen Sie den Preis im Voraus, einschließlich Schätzungen für die voraussichtliche Ankunftszeit und die Entfernung. Die tatsächlichen Kosten und die Zeit können zwar variieren, aber diese Schätzung verringert die Differenz zwischen den erwarteten und den tatsächlichen Routenkosten.

• Erweiterte Routenziele angeben, z. B. verbrauchsarme Routen oder die kürzeste Route.

Tipp: Ein Routentoken gilt für einen bestimmten Start- und Zielort und zu einer bestimmten Zeit. Sie müssen eine neue Routes API- oder Route Optimization API-Anfrage für ein neues Routentoken stellen.

Funktionsweise von Routentokens

Sie können die Routes API oder die Route Optimization API verwenden, um eine Route anhand von Routenzielen zu planen. Sie können ein von einer dieser APIs zurückgegebenes Routentoken an das Navigation SDK übergeben, um die Routenführung für Ihr Fahrzeug zu steuern.

Das passiert, wenn Sie ein Routentoken anfordern und verwenden:

1. Die Routes API oder die Route Optimization API gibt ein verschlüsseltes Routentoken zurück, das die Routenpolylinie und die Routenziele enthält.

2. Sie übergeben das Routentoken an das Navigation SDK.

3. Das Navigation SDK startet die Navigation auf der geplanten Route, auch wenn eine schnellere Route verfügbar ist.

4. Wenn sich während der Fahrt die Verkehrs- oder Straßenverhältnisse ändern oder das Fahrzeug die geplante Route verlässt, berechnet das Navigation SDK eine neue Route, die den Routenzielen und Routingoptionen in Ihrem Routentoken entspricht.

So wird die tatsächliche Route möglichst nah an der geplanten Route gehalten.

Warum eine geplante Route möglicherweise nicht genau eingehalten wird

Die Navigation beginnt auf der geplanten Route, die tatsächliche Route kann jedoch in folgenden Situationen davon abweichen:

• Das Fahrzeug startet nicht am geplanten Startpunkt.
• Die Verkehrs- oder Straßenverhältnisse ändern sich während der Fahrt.
• Das Fahrzeug verlässt die geplante Route.

Diese Unterschiede können sich auf die Entfernung, die voraussichtliche Ankunftszeit und andere wichtige Fahrtmerkmale auswirken, die Sie geplant haben.

Tipp : Als Best Practice sollten Sie immer ein neues Routentoken anfordern, wenn Sie das Ziel im Navigation SDK festlegen. Planen Sie außerdem eine gewisse Abweichung ein, um Auswirkungen auf Ihr Unternehmen zu vermeiden.

Route mit einem Routentoken planen

Sie können eine Route planen, indem Sie ein Routentoken erstellen und es dann an das Navigation SDK übergeben. Gehen Sie dazu so vor:

Schritt 1: Routentoken mit der Routes API oder der Route Optimization API erstellen

1. Fordern Sie ein Routentoken an. Verwenden Sie dazu eine der folgenden Methoden:

   • Routes API: computeRoutes. Weitere Informationen zum Anfordern eines Routentokens in der Routes API finden Sie unter Route berechnen und Routentoken abrufen.

   • Route Optimization API: optimizeTours oder batchOptimizeTours. Weitere Informationen zum Anfordern eines Routentokens in der Route Optimization API finden Sie unter Übergangspolylinien und Routentokens.

2. Richten Sie Ihre Routes API-Anfrage so ein, dass sie die Anforderungen für die Verwendung eines Routentokens erfüllt:

   • Legen Sie travelMode auf DRIVE oder TWO_WHEELER fest.
   • Legen Sie routingPreference auf TRAFFIC_AWARE oder TRAFFIC_AWARE_OPTIMAL fest.
   • Verwenden Sie keine Via-Wegpunkte.

Hinweis: Sie können in Ihrem Routentoken mithilfe eines Navigationspunkt-Tokens genaue Start- und Zielwerte angeben, z. B. Eingänge, Laderampen oder ausgewiesene Abholbereiche.

Schritt 2: Routentoken an das Navigation SDK übergeben

1. Routentoken speichern: Richten Sie im Navigation SDK einen String ein, um das Routentoken zu speichern. Beispiel:

   String routeToken = "route token returned by Routes API";
   

   Beispiel für ein zurückgegebenes Routentoken:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Übergeben Sie das Routentoken mit der Methode Navigator.setDestinationsWithToken an das Navigation SDK. Das Navigation SDK ruft die Ziele und Routingoptionen aus dem Routentoken ab. Sie müssen also keine Wegpunkte oder Verkehrsmittel angeben.

   setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
   setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
   

   Hinweis: Wenn Ihre App eine Version des Navigation SDK vor 8.1 verwendet, verwenden Sie stattdessen die verworfenen setDestinations-Methoden, die CustomRoutesOptions verwenden, und übergeben Sie dieselben Zielwegpunkte, die Sie zum Erstellen des Routentokens verwendet haben.

3. Prüfen Sie den Routenstatus in Ihrem Callback. Wenn das Navigations-SDK die Berechnung der Route abgeschlossen hat, wird ein RouteDescription an den Callback übergeben. Wenn eine Route vom Standort des Fahrzeugs zu den Zielen in Ihrem Routentoken gefunden wird, gibt RouteDescription.getRouteStatus Navigator.RouteStatus.OK zurück und Sie können die Zielführung starten. Beispiel:

   navigator.setDestinationsWithToken(
       routeToken,
       routeDescription -> {
         if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
           navigator.startGuidance();
         }
       });
   

Hinweis: Wenn Sie dieselbe Route noch einmal fahren müssen, fordern Sie ein neues Routentoken an.

Prüfen, ob das Navigation SDK Ihr Routentoken angewendet hat

Der Routenstatus OK bedeutet, dass das Navigation SDK eine Route gefunden hat, aber nicht unbedingt Ihre geplante Route. So prüfen Sie in Ihrem Callback, ob die Route mit der geplanten Route übereinstimmt:

1. Prüfen Sie, ob RouteDescription.getRouteStatus den Wert Navigator.RouteStatus.OK zurückgibt. Das Navigation SDK stellt nur dann Routentokendetails bereit, wenn eine Route gefunden wird. Weitere Informationen finden Sie unter Schritt 2.

2. Rufen Sie RouteDescription.getRouteTokenExecutionDetails auf, um ein RouteTokenExecutionDetails-Objekt zu erhalten. Wenn der Server keine Routentokendetails bereitstellt, gibt diese Methode null zurück.

3. Rufen Sie getTokenExecutionStatus für das RouteTokenExecutionDetails-Objekt auf. Wenn TOKEN_SUCCESSFULLY_APPLIED zurückgegeben wird, entspricht die Route Ihrer geplanten Route. Jeder andere Status bedeutet, dass die Route von der geplanten Route abweichen kann. Weitere Informationen zu den einzelnen Status finden Sie unter Statuswerte für die Tokenausführung.

4. Optional: Wenn der Status TOKEN_SUCCESSFULLY_APPLIED lautet, rufen Sie getResolvedParameters für dasselbe RouteTokenExecutionDetails-Objekt auf, um zu prüfen, welche Routenoptionen für die Route verwendet werden, z. B. ob Mautstraßen vermieden werden. Weitere Informationen finden Sie unter Aufgelöste Routingoptionen.

Werte für den Tokenausführungsstatus

Wenn der Routenstatus OK lautet, können Sie die Navigation mit einem beliebigen Tokenausführungsstatus starten. Der Status gibt an, ob die Route Ihrer geplanten Route entspricht.

Status	Folgt der geplanten Route	Beschreibung
TOKEN_SUCCESSFULLY_APPLIED	Ja	Das Navigation SDK hat Ihr Routentoken angewendet.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	Nicht unbedingt	Das Navigation SDK konnte die geplante Route nicht neu erstellen, da ein Ort in der Routenanfrage mehr als 25 Meter vom entsprechenden Ort im Routentoken entfernt war. Bei setDestinationsWithToken bedeutet das, dass das Gerät mehr als 25 Meter vom Startpunkt im Routentoken entfernt war. Die Route führt weiterhin zu Ihren Zielen, aber das Navigation SDK kann nicht bestätigen, dass die Routenoptionen aus Ihrem Routentoken verwendet werden, z. B. die Vermeidung von Mautstraßen.
TOKEN_IGNORED_OTHER	Nicht unbedingt	Das Navigation SDK konnte die geplante Route aus einem anderen Grund nicht neu berechnen, z. B. weil eine Straße auf der geplanten Route gesperrt ist. Die Route führt weiterhin zu Ihren Zielen, aber das Navigation SDK kann nicht bestätigen, dass die Routenoptionen aus Ihrem Routentoken verwendet werden, z. B. die Vermeidung von Mautstraßen.
NO_TOKEN_PROVIDED	Nicht zutreffend	Die Routenanfrage enthielt kein Routentoken.
UNKNOWN	Unbekannt	Der Status ist unbekannt.

Wenn die Route nicht unbedingt Ihrer geplanten Route folgt und die genaue Route wichtig ist, z. B. weil Sie sie zur Berechnung eines Preises verwendet haben, protokollieren Sie den Status oder fordern Sie ein neues Routentoken vom aktuellen Standort des Fahrzeugs an.

Aufgelöste Routingoptionen

getResolvedParameters gibt ein RouteTokenResolvedParameters-Objekt zurück oder null, wenn die Routenoptionen nicht verfügbar sind. RouteTokenResolvedParameters hat die folgenden Methoden:

• getTravelMode: Der für die Route verwendete Mobilitätsmodus, z. B. RoutingOptions.TravelMode.DRIVING. Das Navigation SDK meldet auch RoutingOptions.TravelMode.DRIVING, wenn die Route einen Reisemodus verwendet, für den kein entsprechender Wert vorhanden ist, oder wenn der Reisemodus nicht verfügbar ist.
• getAvoidTolls: Gibt an, ob auf der Route Mautstraßen vermieden werden.
• getAvoidHighways: Gibt an, ob auf der Route Autobahnen vermieden werden.
• getAvoidFerries: Gibt an, ob auf der Route Fähren vermieden werden.

Beispiel

Im folgenden Codebeispiel wird gezeigt, wie Sie eine Route mit einem Routentoken planen, prüfen, ob das Navigation SDK das Token angewendet hat, und die Zielführung starten.

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

Hinweis: Sie können maximal 25 Wegpunkte konfigurieren.

Interaktion von Routentokens und dem Navigation SDK

So verarbeitet das Navigation SDK Ihre geplante Route:

• Überschreibt alle zuvor festgelegten Ziele.

• Verwendet den Startort des Fahrzeugs.

• Passt sich an die Straßen- und Verkehrslage an. Weitere Informationen finden Sie unter Warum eine geplante Route möglicherweise nicht genau eingehalten wird.

• Verwendet die in Ihrem Routentoken festgelegten Routenoptionen anstelle der folgenden Einstellungen in Ihrer App, auch wenn während der Fahrt eine neue Route berechnet wird:

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • Die in Ihrer App festgelegte Mobilitätsform

• Folgt diesen Einstellungen, wenn die Route berechnet oder angepasst wird:

  • Routenziele aus Ihrem Routentoken, z. B. die umweltfreundliche Route oder die kürzeste Route. Wenn das Navigation SDK die Route anpassen muss, verwendet es die Routenziele, die Sie beim Anfordern des Routentokens angegeben haben.
  • Wegpunktbezogene Optionen aus Ihrem Routentoken, z. B. die bevorzugte Straßenseite.

Hinweis: Bei setDestinationsWithToken übergeben Sie keine Wegpunkte. Das Navigation SDK verwendet daher die Ziele und Wegpunktoptionen aus Ihrem Routentoken. Wenn Sie Wegpunktoptionen wie die bevorzugte Straßenseite oder Zwischenstopps festlegen möchten, verwenden Sie die Felder sideOfRoad und vehicleStopover für die Wegpunkte in Ihrer Routes API-Anfrage. Der Startpunkt ist immer der Standort des Geräts. Optionen, die Sie in Ihrer Routes API-Anfrage für den Startpunkt festlegen, werden daher nicht angewendet.