Follow this guide to plot a route within your app using the Navigation SDK for Android. This guide assumes you have already integrated the Navigation SDK into your app, as described in Set up your project.
Summary
- Add a UI element to your app, either as a navigation fragment or as a navigation view. This UI element adds the interactive map and turn-by-turn navigation UI to your activity.
- Request location permissions. Your app must request location permission to determine the location of the device.
- Initialize the SDK using the
NavigationApi
class. Set a destination and control turn-by-turn navigation using the
Navigator
class. This involves three steps:- Set destination using
setDestination()
. - Start navigation with
startGuidance()
. - Use
getSimulator()
to simulate the progress of the vehicle along the route, for testing, debugging, and demonstrating your app.
- Set destination using
Build and run your app.
See the code
Add a UI element to your app
This section covers two ways you can add the interactive map and UI for displaying turn-by-turn navigation.
Use a navigation fragment
SupportNavigationFragment
is the UI component that displays the visual output of navigation, including an
interactive map and turn-by-turn directions. You can declare the fragment in
your XML layout file as shown here:
<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
android:id="@+id/navigation_fragment"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
Alternatively, you can construct the fragment programmatically, as described in
the Android documentation, using
FragmentActivity.getSupportFragmentManager()
.
Use a navigation view
As an alternative to a fragment, the UI component to display a map for
navigation is also available as a
NavigationView
.
Request location permission
This section illustrates how to request fine location permission. For more details, see the guide to Android permissions.
Add the permission as a child of the
<manifest>
element in your Android manifest:<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.navsdksingledestination"> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> </manifest>
Request runtime permissions in your app, giving the user the opportunity to grant or deny location permission. The following code checks whether the user has granted fine location permission. If not, it requests the permission:
if (ContextCompat.checkSelfPermission(this.getApplicationContext(), android.Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { mLocationPermissionGranted = true; } else { ActivityCompat.requestPermissions(this, new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION }, PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION); } if (!mLocationPermissionGranted) { displayMessage("Error loading Navigation SDK: " + "The user has not granted location permission."); return; }
Override the
onRequestPermissionsResult()
callback to handle the result of the permission request:@Override public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[], @NonNull int[] grantResults) { mLocationPermissionGranted = false; switch (requestCode) { case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: { // If request is canceled, the result arrays are empty. if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) { mLocationPermissionGranted = true; } } } }
Initialize the Navigation SDK
The
NavigationApi
class provides initialization logic that authorizes your app to use Google
navigation. This section covers how to initialize the navigator, along with some
other configurations you can enable for your app:
Initialize the Navigation SDK and override the
onNavigatorReady()
callback to start navigation when the navigator is ready.Optional. Configure the app so that guidance notifications and background services shut down when the user dismisses the app from their device. This choice depends on your business model. You might want to use the default navigator behavior, which continues to display turn guidance and location updates even when the app is dismissed. If instead you want to shut down navigation and location updates when the end user dismissed the app, you would use this configuration.
Optional. Enable road restrictions in supported countries. Set the last digit of the license plate. This call only needs to be made once: subsequent directions requests continue to use it. This call only works on supported regions. See Navigation SDK supported countries.
NavigationApi.getNavigator(this, new NavigationApi.NavigatorListener() { /** * Sets up the navigation UI when the navigator is ready for use. */ @Override public void onNavigatorReady(Navigator navigator) { displayMessage("Navigator ready."); mNavigator = navigator; mNavFragment = (NavigationFragment) getFragmentManager() .findFragmentById(R.id.navigation_fragment); // Optional. Disable the guidance notifications and shut down the app // and background service when the user closes the app. // mNavigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE) // Optional. Set the last digit of the car's license plate to get // route restrictions for supported countries. // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ"); // Set the camera to follow the device location with 'TILTED' driving view. mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED); // Set the travel mode (DRIVING, WALKING, CYCLING, TWO_WHEELER, or TAXI). mRoutingOptions = new RoutingOptions(); mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING); // Navigate to a place, specified by Place ID. navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions); } /** * Handles errors from the Navigation SDK. * @param errorCode The error code returned by the navigator. */ @Override public void onError(@NavigationApi.ErrorCode int errorCode) { switch (errorCode) { case NavigationApi.ErrorCode.NOT_AUTHORIZED: displayMessage("Error loading Navigation SDK: Your API key is " + "invalid or not authorized to use the Navigation SDK."); break; case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED: displayMessage("Error loading Navigation SDK: User did not accept " + "the Navigation Terms of Use."); break; case NavigationApi.ErrorCode.NETWORK_ERROR: displayMessage("Error loading Navigation SDK: Network error."); break; case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING: displayMessage("Error loading Navigation SDK: Location permission " + "is missing."); break; default: displayMessage("Error loading Navigation SDK: " + errorCode); } } });
Set a destination
The
Navigator
class provides control over configuring, starting, and stopping a navigation
journey.
Using the
Navigator
obtained in the previous section, set a destination
Waypoint
for this journey. After calculating directions, the
SupportNavigationFragment
displays a polyline representing the route on the map, and a marker at the
destination.
private void navigateToPlace(String placeId, RoutingOptions travelMode) {
Waypoint destination;
try {
destination = Waypoint.builder().setPlaceIdString(placeId).build();
} catch (Waypoint.UnsupportedPlaceIdException e) {
displayMessage("Error starting navigation: Place ID is not supported.");
return;
}
// Create a future to await the result of the asynchronous navigator task.
ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
mNavigator.setDestination(destination, travelMode);
// Define the action to perform when the SDK has determined the route.
pendingRoute.setOnResultListener(
new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
@Override
public void onResult(Navigator.RouteStatus code) {
switch (code) {
case OK:
// Hide the toolbar to maximize the navigation UI.
if (getActionBar() != null) {
getActionBar().hide();
}
// Enable voice audio guidance (through the device speaker).
mNavigator.setAudioGuidance(
Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);
// Simulate vehicle progress along the route for demo/debug builds.
if (BuildConfig.DEBUG) {
mNavigator.getSimulator().simulateLocationsAlongExistingRoute(
new SimulationOptions().speedMultiplier(5));
}
// Start turn-by-turn guidance along the current route.
mNavigator.startGuidance();
break;
// Handle error conditions returned by the navigator.
case NO_ROUTE_FOUND:
displayMessage("Error starting navigation: No route found.");
break;
case NETWORK_ERROR:
displayMessage("Error starting navigation: Network error.");
break;
case ROUTE_CANCELED:
displayMessage("Error starting navigation: Route canceled.");
break;
default:
displayMessage("Error starting navigation: "
+ String.valueOf(code));
}
}
});
}
Build and run your app
- Connect an Android device to your computer. Follow the Android Studio instructions on how to Run apps on a hardware device Alternatively, you can configure a virtual device using the Android Virtual Device (AVD) Manager. When choosing an emulator, make sure you pick an image that includes the Google APIs.
- In Android Studio, click the Run menu option or the play button icon. Choose a device as prompted.
Hints for improved user experience
- The user must accept the Google Navigation Terms of Service before
navigation becomes available. This acceptance is only required once. By
default, the SDK prompts for acceptance the first time the navigator is
invoked. If you prefer, you can trigger the Navigation Terms of Service dialog
at an early point in your app's UX flow, such as during signup or login, using
TermsAndConditionsCheckOption
. - To significantly improve navigation quality and ETA accuracy, use place IDs to initialize a waypoint rather than latitude/longitude coordinates.
- This sample derives the destination waypoint from a specific place ID for the Sydney Opera House. You can use the place ID finder to get place IDs for other specific locations.