Navigation SDK is currently available only to select customers. Contact sales to learn more.

Enable turn-by-turn guidance feed

Stay organized with collections Save and categorize content based on your preferences.

A turn-by-turn guidance feed provides navigation-only information to devices not designed for map-based navigation guidance. It provides upcoming maneuvers with elements you supply:

  • icons (left, right, U-turn)
  • turn numbers in roundabouts
  • road names
  • estimated distances and time to the next navigation step or final destination

You can use the turn-by-turn feed to create experiences where the full Navigation SDK UI is not appropriate, such as for Android Auto or for small screen displays where a full Android stack is not available. For example, you might use this for two-wheeled vehicle riders, where you can project navigation-only guidance to help them reach their destinations faster and more confidently with minimal distractions.

To use the SDK, you'll create a service and register it with the Navigation SDK for Android so that it can receive new navigation information in real time (about once a second during navigation).

This document shows you how to create and register a navigation service that receives navigation information from the SDK and provides the navigation state to the receiving device.

Overview

This section describes how to add the TurnByTurn library to your projects and summarizes the high-level flow for building turn-by-turn functionality.

To consume a standalone version of the TurnByTurn library, follow these steps:

  1. Set up your environment to access the host Maven repository as described in Getting started with the Driver SDK in the Trip and Order Documentation.

  2. Add the following dependency to your Maven or Gradle configuration:

    Maven

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.maps</groupId>
    <artifactId>google_turnbyturn</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>

    Gradle

    dependencies {
  ...
  implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
}

Add the TurnByTurn library to your project using a downloaded JAR file (alternative)

The TurnByTurn library is available as a JAR file in this SDK folder. If you don't have access, contact your representative.

  1. Download and unzip google_turnbyturn_*.jar.
  2. Copy the downloaded JAR file into your project's app/libs directory.

  3. Add the following to your build.gradle to include the JAR in your build.

    dependencies {
   ...
   api fileTree(include: ['*.jar'], dir: 'libs')
}

Using the TurnByTurn Library

Here are the high-level steps for enabling turn-by-turn functionality. The sections that follow provide details about each step.

  1. Create a service to receive navigation updates.

  2. Register the service.

  3. Understand navigation states.

  4. See a navigation display example that shows essential elements.

Create a service to receive navigation updates

The Navigation SDK binds to your TurnByTurn service and sends it navigation updates through the Android Messenger . You can create a new navigation service for these updates, or use an existing service.

The benefit of using a service to receive navigation updates is that the service can live in a separate background process.

The service in the following example receives navigation information and uses the TurnByTurnManager to convert the data into a NavInfo object that contains the navigation details.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

Message codes

NavInfo messages can be identified through the Message.what field of the Message class, which is set to the value of TurnByTurnManager.MSG_NAV_INFO.

Registering the service for navigation updates

The following code snippets registers the navigation service.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

Starting and stopping the service

The navigation service is active as long as the Navigation SDK binds to it. You can manually call startService() and stopService() to control the navigation service life cycle, but when you register your service with the Navigation SDK, your service starts automatically, and only stops when you unregister it. Depending on how you set up your app, you may want to consider starting a foreground service, described in the Android documentation Services overview.

Unregistering the service

To stop receiving navigation updates, unregister the service from the Navigation SDK.

navigator.unregisterServiceForNavUpdates();

Understand navigation states

Use NavInfo.getNavState() to get the current state of navigation, which is one of the following:

  • Enroute - The ENROUTE state means that guided navigation is currently active and the user is on the provided route. Information about the current upcoming maneuver step is available.

  • Rerouting - REROUTING means that navigation is in progress, but the navigator is looking for a new route. The upcoming maneuver step is not available, because there's no new route yet. In the sample app, a “Rerouting...” message appears in the navigation info display. Once a route is found, a NavInfo message is sent with the state ENROUTE.

  • Stopped - STOPPED means navigation has ended. For example, navigation stops when the user exits navigation in the app. In the sample app, a STOPPED state clears the navigation info display to prevent lingering step instructions from being displayed.

What's next

Now that you have your service operational, consider the following: