Provide turn-by-turn navigation for large vehicles

Who this guide is for: Read this guide if you are a mobile developer responsible for building the in-cab navigation experience for drivers of trucks or other large vehicles.

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

What you'll learn

You'll learn how to do the following:

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

Prerequisites

Before you begin, you must meet the following requirements.

Project setup

Large vehicle routing is available to a limited set of customers, contact us to request access. Once you receive access, ensure your Google Cloud project is provisioned for large vehicle routing. If you use separate projects for the Routes API and the Navigation SDK, you must provision both projects.

Generate a route token

You must first generate a route by following the instructions in the Generate truck routes & ETAs guide. The output of that process, a routeToken, is required to complete the steps in this guide.

Minimum requirements

Your app must use the minimum required Navigation SDK version:

  • Android: 5.2.0 or later
  • iOS: 5.4.0 or later

In addition, all the requirements for using the Navigation SDK apply:

Limitations

Before you begin, you must be aware of the following limitations and requirements.

  • Geographic availability: Large vehicle routing is available only in the contiguous 48 United States.
  • Driver advisory and safety. Drivers must not rely solely on routes returned by this API to be safe or legal. Routes are not guaranteed to be appropriate for the vehicle, and following them may expose drivers to hazards such as low bridges or roads where large vehicles are prohibited.
  • Best-effort routes. In some cases, the API cannot find a route that fully complies with travel restrictions. Instead, it returns a "best effort" route that may still traverse restricted areas. The Routes API response clearly flags these routes in the routeRestrictionsPartiallyIgnored field. Plan your route carefully in these cases, ideally using other source data. Don't use a flagged route as a single source of truth for planning or navigation.
  • Unsupported features: Large vehicle routing does not support the following:
    • Truck toll prices
    • Speed limits
    • Routing for radioactive hazardous materials
  • Usage limits: All requests are subject to standard query-per-second (QPS) limits.

Display truck-specific UI

The Navigation SDK automatically displays visual warnings, called route callouts, on the map to warn drivers of upcoming truck restrictions. Callouts are rendered for restrictions that are part of the planned route, but not on other nearby roads.

The SDK includes callouts for the following restrictions:

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

Route token workflow

A routeToken is an encrypted, secure snapshot of a route generated by the Routes API. It contains all the route details, including the vehicle information used to create it. Using a token ensures the navigation session matches the route you planned on your backend.

Note that once the driver starts navigating, the route presented by navigation SDK can change depending on traffic and road conditions. In some cases it may diverge from the route specified by the route token.

In these cases, as well as in the case where the driver deviates from the planned route, usage of the route token ensures that newly recalculated routes respect the vehicle attributes as configured in the original Routes API request.

The workflow follows these steps:

  1. Your backend requests a truck route from the Routes API.
  2. The Routes API returns a routeToken.
  3. Your backend sends this token to your mobile application.
  4. The mobile app passes the routeToken to the Navigation SDK to start the trip.
  5. The Navigation SDK handles all aspects of the turn-by-turn experience, including rerouting if the driver deviates from the path while preserving the original vehicle restrictions.

Implementation: Start a truck-specific trip

To launch a navigation session with your truck route, you pass the route token to the Navigator.

Step 1: Obtain the route token

Your application receives the routeToken string from your backend server.

The following code is an example token:

CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g

Step 2: Pass the token to the Navigator

Provide the routeToken to the Navigator when you set the trip destination. The Navigation SDK then uses this token for all route calculations for the trip.

Note that Navigation SDK has a TravelMode configuration, which must be set to TravelMode.DRIVING. This is separate from the travelMode configuration in Routes API, which must be set to TRUCK. The Routes API travelMode configuration is encoded in the routeToken and signals Navigation SDK to display the truck-specific experience and route.

Android

Use CustomRoutesOptions.builder() to set the token and then pass it to navigator.setDestinations().

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

val customRoutesOptions = CustomRoutesOptions.builder()
    .setRouteToken(routeToken)
    .setTravelMode(TravelMode.DRIVING)
    .build()

// Specify the same destination used to create the route token
ArrayList <Waypoint> destinations = Lists.newArrayList();
val destination = Waypoint.builder()
    .setLatLng(10.0, 20.0)
    .setTitle("title")
    .setVehicleStopover(true)
    .build()
destinations.add(destination);

navigator.setDestinations(destinations, customRoutesOptions)

iOS

Pass the route token to the Navigation SDK using the mapView.navigator setDestinations method, specifying the same destination waypoints that you used when creating the route token:

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

mapView.navigator?.setDestinations([destination], routeToken: routeToken, callback: {...})

Next Steps