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

Navigation-only data feed

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

A navigation-only data feed provides navigation-only information to devices not designed for map-based navigation guidance. It provides upcoming maneuvers with icons (left, right, U-turn), turns numbers in roundabouts, road names, and estimated distances and time to the next navigation step or final destination.

You can use this feed to create experiences where the full Navigation SDK UI is not appropriate, such as for small screen displays or devices 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 topic shows you how to create and register a service that receives navigation information and turns it into a turn-by-turn navigation experience for your users.

Overview

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

You can add TurnByTurn to your project using Maven or Gradle.

  1. Set up your environment to access the host Maven repository as described in Android SDK Setup.

  2. In addition to including the Navigation SDK dependency as described in Set up your project, 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 TurnByTurn to your project using a downloaded JAR file (alternative)

The TurnByTurn SDK 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 SDK

Here are the high-level steps for building TurnByTurn functionality. The sections that follow provide details about each step.

  1. Create a service to receive navigation updates

  2. Register the service

  3. Create icons for maneuvers

  4. Understand navigation states

  5. See a navigation display example that shows essential elements

Creating a service to receive navigation updates

The Navigation SDK binds to your TurnByTurn service and sends navigation updates to it through a Messenger. You can create a new service 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, which will receive navigation information, 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, which is set to the value of TurnByTurnManager.MSG_NAV_INFO. Set aside the value range 7200-7299, as the Navigation SDK may use message codes in that range in the future.

Registering the service for navigation updates

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

Starting and stopping the service

The service will be active as long as the Navigation SDK binds to it. You can manually call startService() and stopService() to control the 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();

Creating icons for maneuvers

The Maneuver enum defines each possible maneuver that could occur while navigating, and you can get the maneuver for a given step from the StepInfo.getManeuver() method.

You must create maneuver icons and pair them with their associated maneuvers. For some maneuvers, you can set up a one-to-one mapping to an icon, such as DESTINATION_LEFT and DESTINATION_RIGHT. However, since some maneuvers are similar, you might want to map more than one maneuver to a single icon. For example TURN_LEFT and ON_RAMP_LEFT could both map to the left turn icon.

Some maneuvers contain an additional “clockwise” or “counterclockwise” label, which the SDK determines based on the driving side of a country. For example, in countries where driving is on the left side of the road, drivers take a roundabout or U-turn in a clockwise direction, whereas right-side-of-the-road countries go clockwise. The Navigation SDK detects whether a maneuver occurs in left- or right-side traffic and outputs the appropriate maneuver. Therefore, your maneuver icon may be different for a clockwise versus a counterclockwise maneuver.

Expand to see examples icons for different maneuvers

Sample Icon TurnByTurn Maneuvers
DEPART
UNKNOWN
STRAIGHT
ON_RAMP_UNSPECIFIED
OFF_RAMP_UNSPECIFIED
NAME_CHANGE
TURN_RIGHT
ON_RAMP_RIGHT
TURN_LEFT
ON_RAMP_LEFT
TURN_SLIGHT_RIGHT
ON_RAMP_SLIGHT_RIGHT
OFF_RAMP_SLIGHT_RIGHT
TURN_SLIGHT_LEFT
ON_RAMP_SLIGHT_LEFT
OFF_RAMP_SLIGHT_LEFT
TURN_SHARP_RIGHT
ON_RAMP_SHARP_RIGHT
OFF_RAMP_SHARP_RIGHT
TURN_SHARP_LEFT
ON_RAMP_SHARP_LEFT
OFF_RAMP_SHARP_LEFT
TURN_U_TURN_COUNTERCLOCKWISE
ON_RAMP_U_TURN_COUNTERCLOCKWISE
OFF_RAMP_U_TURN_COUNTERCLOCKWISE
TURN_U_TURN_CLOCKWISE
ON_RAMP_U_TURN_CLOCKWISE
OFF_RAMP_U_TURN_CLOCKWISE
ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_RIGHT_CLOCKWISE
ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
ROUNDABOUT_STRAIGHT_CLOCKWISE
ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
ROUNDABOUT_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_LEFT_CLOCKWISE
ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_SHARP_LEFT_CLOCKWISE
ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
ROUNDABOUT_U_TURN_CLOCKWISE
ROUNDABOUT_COUNTERCLOCKWISE
ROUNDABOUT_CLOCKWISE
ROUNDABOUT_EXIT_COUNTERCLOCKWISE
ROUNDABOUT_EXIT_CLOCKWISE
MERGE_RIGHT
OFF_RAMP_RIGHT
MERGE_LEFT
OFF_RAMP_LEFT
FORK_RIGHT
TURN_KEEP_RIGHT
ON_RAMP_KEEP_RIGHT
OFF_RAMP_KEEP_RIGHT
FORK_LEFT
TURN_KEEP_LEFT
ON_RAMP_KEEP_LEFT
OFF_RAMP_KEEP_LEFT
MERGE_UNSPECIFIED
DESTINATION
DESTINATION_RIGHT
DESTINATION_LEFT
FERRY_BOAT
FERRY_TRAIN

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

Essential navigation display elements

The primary fields for each navigation step are the full road name, maneuver icon, and distance to the next step, which are available in StepInfo. For the overall trip, you may want to display the remaining time and distance to the destination, both of which are available in NavInfo. The following image shows an example of these essential navigation elements.

A mobile screen that displays an upcoming left turn in 100 feet onto
W Ahwanee Ave. At the bottom of the screen, time remaining to destination
is 46 minutes, and distance remaininig is 39 miles.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2022-09-26 UTC.