Route planen

Manchmal möchten Sie vielleicht die Route planen, die Ihre App den Nutzern vorschlägt. Mit einem Routentoken aus der Routes API, der Routes Preferred 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.

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, der Routes Preferred 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.

Funktionsweise von Routentokens

Sie können die Routes API, die Routes Preferred 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, die Routes Preferred 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.

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, der Routes Preferred 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.

   • Routes Preferred API: computeCustomRoutes. Weitere Informationen zum Anfordern eines Routentokens in der Routes Preferred API finden Sie unter Route planen.

   • 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- oder Routes Preferred API-Anfrage so ein, dass die Anforderungen für die Verwendung eines Routentokens erfüllt werden:

   • 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.

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:

   let 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 setDestinationsWithToken:completionHandler: von mapView.navigator an das Navigation SDK. Das Navigation SDK ruft die Ziele und Routenoptionen aus dem Routentoken ab, sodass Sie keine Wegpunkte übergeben müssen.

   Der in Ihrer App festgelegte Mobilitätsmodus, z. B. mapView.travelMode, muss einer der folgenden Werte sein:

   • .driving (GMSNavigationTravelModeDriving): Autofahren. Dies ist der Standardwert, sodass die meisten Apps ihn nicht ändern müssen.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): Zweirad.

   Bei allen anderen Mobilitätsformen schlägt die Anfrage mit .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported) fehl. Bei beiden unterstützten Werten wird die Mobilitätsform in Ihrem Routentoken verwendet. Wenn Ihre App beispielsweise für Autofahrten gedacht ist und Ihr Routentoken für eine Zweiradroute gilt, stellt das Navigation SDK eine Zweiradroute bereit. Welche Mobilitätsform für die Route verwendet wird, können Sie unter resolvedParameters.travelMode nachsehen. Weitere Informationen finden Sie unter Aufgelöste Routingoptionen.

3. Prüfen Sie den Routenstatus im Completion Handler. Wenn das Navigation SDK die Berechnung der Route abgeschlossen hat, wird ein GMSNavigationRouteDescription an den Completion Handler übergeben. Wenn eine Route vom Standort des Fahrzeugs zu den Zielen im Routentoken gefunden wird, lautet der routeStatus der Routenbeschreibung .OK (GMSRouteStatusOK) und Sie können die Zielführung starten. Andernfalls erhält der Abschluss-Handler auch einen NSError, der den Fehler beschreibt. Beispiel:

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

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, ob die Route mit der geplanten Route übereinstimmt:

1. Prüfen Sie, ob die routeStatus der Routenbeschreibung .OK ist. Das Navigations-SDK stellt nur dann Routentokendetails bereit, wenn eine Route gefunden wird. Weitere Informationen finden Sie unter Schritt 2.

2. Rufen Sie die routeTokenExecutionDetails der Routenbeschreibung ab, ein Objekt, das dem GMSNavigationRouteTokenExecutionDetails-Protokoll entspricht. Wenn der Server keine Routentokendetails bereitstellt, ist diese Property nil.

3. Prüfen Sie das Attribut tokenExecutionStatus der Ausführungsdetails. Wenn der Wert .tokenSuccessfullyApplied ist, 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 .tokenSuccessfullyApplied lautet, prüfen Sie das Attribut resolvedParameters der Ausführungsdetails, um zu sehen, welche Routenoptionen die Route verwendet, z. B. ob Mautgebühren vermieden werden. Weitere Informationen finden Sie unter Aufgelöste Routingoptionen.

Werte für den Tokenausführungsstatus

Wenn routeStatus den Wert .OK hat, können Sie die Anleitung mit einem beliebigen Token-Ausführungsstatus starten. Der Status gibt an, ob die Route Ihrer geplanten Route entspricht.

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

resolvedParameters ist ein Objekt, das dem Protokoll GMSNavigationRouteTokenResolvedParameters entspricht, oder nil, wenn die Routenoptionen nicht verfügbar sind. Sie hat folgende Attribute:

• travelMode: Die Mobilitätsform, die für die Route verwendet wird, z. B. .driving (GMSNavigationTravelModeDriving). Das Navigation SDK meldet auch .driving, wenn für die Route eine Mobilitätsform verwendet wird, für die kein entsprechender Wert vorhanden ist, oder wenn die Mobilitätsform nicht verfügbar ist.
• avoidTolls: Gibt an, ob auf der Route Mautstraßen vermieden werden.
• avoidHighways: Gibt an, ob auf der Route Autobahnen vermieden werden.
• avoidFerries: Gibt an, ob auf der Route Fähren vermieden werden.
• avoidTunnels: Gibt an, ob die Route so berechnet wurde, dass Tunnel nach Möglichkeit vermieden werden.
• avoidVignettes: Die Länder, in denen die Route so berechnet wurde, dass Mautvignetten nach Möglichkeit vermieden werden, als zweistellige Unicode-CLDR-Regionscodes, z. B. CH für die Schweiz.
• rerouteStrategy: Die Strategie, die das Routing-Backend verwendet, um während der Fahrt neue Routen zu berechnen. Zu den Strategien gehört .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), bei der die Routingparameter in Ihrem Routentoken verwendet werden, um neue Routen zu berechnen.

Wenn der Status der Tokenausführung nicht .tokenSuccessfullyApplied ist, meldet das Navigation SDK nur travelMode, avoidTolls, avoidHighways und avoidFerries. Die anderen Properties haben ihre Standardwerte, auch wenn Sie beim Anfordern des Routentokens angegeben haben, dass Tunnel oder Mautvignetten vermieden werden sollen: avoidTunnels ist false (NO), avoidVignettes ist leer und rerouteStrategy ist .unknown (GMSNavigationRerouteStrategyUnknown).

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.

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

Szenarien mit mehreren Zwischenstopps

Sie können maximal 25 Wegpunkte konfigurieren.

Das Navigation SDK wechselt nicht automatisch zum nächsten Ziel. Wenn das Fahrzeug an einem Wegpunkt ankommt, rufen Sie continueToNextDestinationWithCompletion: auf, um den nächsten Abschnitt der Fahrt zu starten. Das gilt auch für Routentokens mit Zwischenwegpunkten. Wenn Sie zum nächsten Ziel weiterfahren, folgt das Navigation SDK der Route aus Ihrem Routentoken, anstatt eine neue Route zu planen.

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:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • 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.