Navigate large vehicle routes

Who this guide is for: Read this guide if you're a mobile developer responsible for building the turn-by-turn navigation experience for drivers of trucks, buses, or other large commercial vehicles.

What this guide covers: This guide explains how to take a truck-specific route generated by the Routes API or Route Optimization API and use it to power a turn-by-turn navigation session with the Navigation SDK for iOS.

What you'll learn

You'll learn how to do the following tasks:

• Use a routeToken to connect backend route planning with the in-app navigation experience.
• Configure the Navigation SDK to use a pre-planned truck route.
• Understand how truck-specific restrictions appear to the driver in the navigation UI.

Prerequisites

Before you begin, ensure you meet the following requirements:

1. Request access for your project

Large vehicle routing is available to a limited set of customers. To express interest and request access for your Google Cloud project, fill out the contact form. A Google representative will reach out with next steps.

After Google grants access, ensure your Google Cloud project is provisioned for large vehicle routing.

If your organization uses separate Google Cloud projects for the backend routing APIs and the mobile Navigation SDK, contact Google to provision each project.

2. Set up backend route generation and obtain a route token

Before starting navigation on the device, your backend server must generate a truck route and obtain a routeToken using one of the following APIs:

• Routes API: Recommended for calculating single truck routes between origins and destinations. For setup instructions, see Generate large vehicle routes & ETAs.
• Route Optimization API: Recommended for optimizing multi-stop routes across a fleet. For more information, see the Route Optimization API large vehicle routing guide.

Your backend request must specify travelMode: TRUCK along with the vehicle's physical attributes (height, width, length, weight, axle count, and hazmat cargo). The routing API returns a routeToken in its response, which your backend server passes to your mobile app.

3. Meet minimum SDK and system requirements

In addition, your project must meet standard Navigation SDK setup requirements.

Limitations and operational guidelines

Before you begin, note the following limitations and operational guidelines:

• Geographic availability: Large vehicle routing is available in the contiguous 48 United States (Generally Available) and Japan (Experimental). It isn't available in Alaska, Hawaii, or US territories.
• Driver advisory and safety: Drivers must not rely solely on routes returned by the Navigation SDK to be safe or legal. Routes might not be suitable for the vehicle in all road conditions, and following them could expose drivers to hazards such as low clearances or weight-restricted roads. Drivers must always remain alert and obey posted road signs and local regulations.
• Best-effort routes: When the routing API can't find a route that fully complies with vehicle restrictions, it returns a "best effort" route that might still traverse restricted segments. For example, the Routes API sets the routeRestrictionsPartiallyIgnored flag in its response. When navigating these routes, the Navigation SDK displays route callouts to highlight the relevant restrictions. Plan routes carefully in these cases and don't use a flagged route as a single source of truth for planning or navigation.
• Unsupported features: Large vehicle routing doesn't support the following features:
  • Truck toll pricing
  • Truck or heavy vehicle-specific speed limits
  • Routing for radioactive hazardous materials
• Usage limits: Requests made to the Navigation SDK follow standard usage and quota limits. For more information, see Usage and billing.

Display truck-specific UI (route callouts)

The Navigation SDK automatically displays visual warnings, called route callouts, on the map to alert drivers to upcoming truck restrictions. Callouts appear for restrictions that occur along the planned route, but not on other nearby roads.

The Navigation SDK includes callouts for the following restrictions:

Restriction	Callout icon & text	Conditions for display
Height	Yellow = warning, your vehicle is close to the maximum height allowed Red = your vehicle is above the maximum height allowed	A yellow callout appears when the vehicle's height is close to the restriction. A red callout appears if the route is non-compliant and violates a height restriction.
Weight		A red callout appears when the vehicle's weight exceeds the road's limit.
Trucks Prohibited		A red callout appears when traveling on a road segment with a commercial truck restriction.
Hazardous Goods		A red callout appears when the vehicle's hazmat load is prohibited on a road segment.

How route tokens work

A routeToken is an encrypted snapshot of a route created by Google's routing backend. It encapsulates the planned route geometry as well as the vehicle's physical dimensions and restriction profile.

The workflow follows these steps:

1. Request route: Your backend server requests a truck route from the Routes API (or Route Optimization API).
2. Receive token: The routing API calculates the compliant route and returns a routeToken to your backend server.
3. Forward token: Your backend server passes the routeToken and destination coordinates to your mobile app.
4. Pass to SDK: The mobile app passes the routeToken to the Navigation SDK.
5. Start guidance: The Navigation SDK handles all aspects of the turn-by-turn experience, including rendering route callouts and handling dynamic rerouting according to the vehicle's restrictions.

Dynamic recalculations and rerouting

During active navigation, traffic conditions, road closures, or missed turns might cause the vehicle to deviate from the planned route.

When rerouting occurs:

• The Navigation SDK automatically recalculates the route to the destination.
• The SDK retains the vehicle attributes and dimensions encoded in the original routeToken.
• The newly recalculated route avoids low clearances, weight-limited bridges, and roads prohibited for commercial trucks.

Implementation: Start a truck-specific trip

Follow these steps to initialize and start turn-by-turn navigation with a large vehicle route token.

Step 1: Obtain the route token from your backend

Your mobile app receives the routeToken string along with the destination coordinates from your backend server. For more information about generating this token on your server, see Generate large vehicle routes & ETAs in the Routes API documentation.

The following code is an example route token:

{
  "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}

Step 2: Set destinations with the route token

Pass the routeToken to the mapView.navigator setDestinationsWithToken:completionHandler: method. The Navigation SDK gets the destinations from the route token, along with the TRUCK routing profile that directs it to apply large vehicle constraints. You don't need to pass waypoints. Your app's travel mode must be .driving (GMSNavigationTravelModeDriving), which is the default, or .twoWheeler (GMSNavigationTravelModeTwoWheeler).

Set waypoint options in the Routes API request that creates the route token. The Navigation SDK gets them from the token, along with your destinations. For large vehicles, consider the following options:

• Side-of-road routing: Large commercial vehicles can't easily make U-turns on narrow streets. To ensure the truck approaches the destination on the correct side of the road, set sideOfRoad to true on the destination waypoint.
• Vehicle stopovers: To guide the truck to an appropriate location for stopping or unloading, set vehicleStopover to true on the destination waypoint.
• Navigation points: If your destination has a designated freight entrance or loading dock, specify it using a navigation point token.

Step 3: Handle route status and start guidance

When the Navigation SDK finishes calculating the route, it passes a GMSNavigationRouteDescription to your completion handler. When its routeStatus is .OK (GMSRouteStatusOK), set isGuidanceActive = true (guidanceActive = YES) to begin active turn-by-turn guidance.

To confirm that the Navigation SDK applied your route token, see Check whether the Navigation SDK applied your route token.

Code example

Pass the route token to setDestinationsWithToken:completionHandler:, and then start guidance when the route status is .OK.

// Obtain the routeToken string from your backend
let routeToken = "route token returned by Routes API"

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

In-vehicle displays

Next steps

• Modify the navigation UI: Customize built-in UI controls and visual elements, such as the compass, recenter button, and camera perspective.
• Listen for navigation events: Handle navigation updates and lifecycle events, such as route progress, ETA changes, and reroutes.