Route progress

SDKs covered:
Navigation SDK
Navigation UI SDK

Tracking a user's progress along a route is key to providing helpful and prompt navigation instructions. The RouteProgress class contains all the user's progress information along the route, including legs and steps. This object is provided inside ProgressChangeListener, allowing you to get distance measurements, the percentage of route complete, current step index, and much more.

Listening to progress change

Like tracking user location changes, the ProgressChangeListener is invoked every time the user's location changes and provides an updated RouteProgress object. The Navigation UI SDK uses this listener by default, but if you are not using the Navigation UI SDK, it is strongly encouraged that you also use this listener. The ProgressChangeListener can typically be used to refresh most of your application's user interface when a change occurs. For example, if you are displaying the user's current progress until the user needs to do the next maneuver. Every time this listener's invoked, you can update your view with the new information from RouteProgress.

Besides receiving information about the route progress, the callback also provides you with the user's current location, which can provide their current speed, bearing, etc. If you have the snap-to-route enabled, the location object will be updated to give the snapped coordinates.

navigation.addProgressChangeListener(new ProgressChangeListener() {
@Override
public void onProgressChange(Location location, RouteProgress routeProgress) {
}
});

Information about progress

There are three classes that contain information on route progress at different levels of granularity: route, leg, and step.

Route: The blue line is a route. A route stretches between the origin and destination.

Leg: The larger circles with a pink stroke represent waypoints, or stops, along the route. A leg is the part of the route between two waypoints.

Step: The smaller circles with a green stroke represent maneuvers. A step is the part of the leg between two maneuvers.

RouteProgress

This class contains all progress information at any given time during a navigation session. This progress includes information for the current route, leg and step the user is traversing along. With every new valid location update, a new route progress will be generated using the latest information.

RouteProgress APIsDescription
directionsRouteThe route acquired from the directions API and being used for navigation.
distanceTraveledThe total distance the user has traveled along the route.
legIndexThe route's current leg index that the user's on.
currentLegThe route's current leg as a routeLeg object.
distanceRemainingProvides the distance remaining in meters till the user reaches the end of the route.
durationRemainingThe estimated duration remaining till the user arrives at their destination.
fractionTraveledA float value between 0 and 1 giving the total percentage the user has completed in the navigation session, based on distance.
currentLegProgressreturns the LegProgress object with information specific to the current route leg. You can also access step information through this object.
remainingWaypointsNumber of waypoints remaining on the current route.
currentStepPointsList of Points representing the current step geometry.
upcomingStepPointsList of Points representing the upcoming step geometry.
voiceInstructionThe current VoiceInstruction for the given segment along the route.
currentStateRouteStateProgress is the current state of route initialization and location tracking along the route.

RouteLegProgress

This is a progress object specific to the current leg the user is on. If there is only one leg in the directions route, much of this information will be the same as the parent RouteProgress.

RouteLegProgress APIsDescription
currentStepProgressreturns the stepProgress object with information specific to the current route step.
stepIndexThe route's current step index the user's on.
distanceTraveledTotal distance the user has traveled along the current leg.
durationRemainingThe estimated duration remaining till the user reaches the last maneuver in current route leg.
fractionTraveledA float value between 0 and 1 giving the total percentage the user has traveled along the current route leg, based on distance.
distanceRemainingThe total distance the user has traveled along the current leg.
previousStepGet the previous step the user traversed along, if the user is still on the first step, this will return null.
currentStepReturns the current step the user is traversing along. Should be used to provide voice / banner instructions.
upComingStepGet the next/upcoming step after the current step. If the user is on the last step on the last leg, this will return null since a next step doesn't exist.
currentLegAnnotationProvides the current annotation data that the Location updates are traveling along. Note: the DirectionsRoute must be requested with ANNOTATION_DISTANCE to enable this within the RouteProgress - this by default in NavigationRoute.

RouteStepProgress

This is a progress object specific to the current step the user is on.

RouteStepProgress APIsDescription
distanceTraveledTotal distance the user has traveled along the current step.
durationRemainingThe estimated duration remaining till the user reaches the next step maneuver.
fractionTraveledA float value between 0 and 1 giving the total percentage the user has traveled along the current step.
distanceRemainingThe total distance the user has traveled along the current step.
currentIntersectionAn intersection is considered a current intersection once passed through and will stay so until a different intersection is passed through.
upcomingIntersectionThe intersection being traveled towards on the route. Will be null if the upcoming step is null (last step of the leg).

Using NavigationView in your XML gives you the ability to listen to different updates or events that may occur during navigation. Both the ProgressChangeListener (see above) and MilestoneEventListener (see the Maneuver instructions guide) from our core SDK are able to be added, as well as RouteListener.

help
Note

This listeners is only available if you are adding NavigationView to your Activity or Fragment layout XML via NavigationViewOptions. You are not able to add them to NavigationLauncherOptions.

RouteListener

CallbackDescription
allowRerouteFrom(Point offRoutePoint)Will trigger in an off-route scenario:
  • Given the Point the user has gone off-route, this listener can return true or false.
  • Returning true will allow the SDK to proceed with the re-route process and fetch a new route with this given off-route Point.
  • Returning false will stop the re-route process and the user will continue without a new route in the direction they are traveling.
onOffRoute(Point offRoutePoint)Will trigger only if RouteListener#allowRerouteFrom(Point) returns true. This serves as the official off-route event and will continue the process to fetch a new route with the given off-route Point.
onRerouteAlong(DirectionsRoute directionsRoute)Will trigger when a new DirectionsRoute has been retrieved post off-route. This is the new route the user will be following until another off route event is triggered.
onFailedReroute(String errorMessage)Will trigger if the request for a new DirectionsRoute fails. Provides the error message from the directions API used to retrieve the DirectionsRoute.

More about route progress

Read more about route progress in:

  • Off-route detection: Detect whether a user is on the generated route throughout their trip. If a user is off-route, provide additional instruction or generate a new route.
  • Faster-route detection: Specify when to check for faster routes and how to determine if a route is faster, then retrieve and initialize faster routes.