Route Overview API

The Route Overview API is a Last Mile Fleet Solution product built on the DriverSDK. With it, you can retrieve route information for a given vehicle, either as a one-time fetch or continuously by using a listener for updates. The Route Overview API supports the following kinds of information:

  • Full route plan, including vehicle stop locations, travel times, distances
  • The route polyline path between each stop.

This document describes integration steps with the API for your application.

Prerequisites

  • You must be running your Android application using the alpha channel of the DriverSDK v4.1.0 or higher. The alpha channel is available by using transportation-driver-alpha for the Maven artifactId.
  • The API consumes route information provided by Fleet Engine via the Deliveries API. This can be provided either through the APIs on DriverSDK (DeliveryDriverApi) or directly to Fleet Engine.

Integration steps

This section covers the basic steps needed to integrate your Android driver app with the API. These instructions have the following assumptions:

  • You have an existing Android app that has already integrated with the Driver SDK
  • You have initialized the DeliveryDriverApi in your app with a context object you can find

See Getting Started with the Driver SDK for Android for details.

Step 0 - Route setup

You can skip this step if you have already set up Fleet Engine and can create vehicle stops and delivery tasks.

To load the stop and task info to Fleet Engine, you need a delivery vehicle assigned to a valid route. This is because the Route Overview API requires valid routes in order to fetch data. Valid routes are comprised of a series of waypoints and stops, and a stop can only exist if it has at least one associated task. See the Fleet Engine API integration guide for more information.

Step 1 - Initialize the API

Once you establish a valid route with associated stops and tasks, you can initialize the Route Overview API. Initialization provides the framework necessary for the connection between Fleet Engine and the API. The Route Overview API should be initialized with the same context object you used to initialize DeliveryDriverApi in the DriverSDK, since the object refers to the same vehicle ID defined previously in your DriverContext object. The following example illustrates how to create an instance of RouteOverviewApi.


RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

Step 2 - Register vehicle for route change events

Now that you have initialized the API, you can use the VehicleRouteOverview object to interact with route overview capabilities. This allows your application to consume the route information you provided during route setup. Use the API event listener to facilitate event updates and route retrieval.

A route change event occurs whenever the path to any of the stops assigned to the vehicle is updated, a stop is rearranged, or when Fleet Engine updates the ETA information.


vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

Step 3 - Enable the API

Now that you are ready to consume route information, you must enable the API to allow it to respond to vehicle events. Remember that the API is initialized in a disabled state to avoid unnecessary consumption of network bandwidth.

vehicleRouteOverview.setRouteOverviewEnabled(true);

You can pause these updates at any time by calling the same method with the value of false.

Step 4 - Draw the route on a Google Map

Once you get a list of RouteToVehicleStops, you can use it in your application. For example, you can draw the route polyline path in a Google Map instance. The following code snippet shows an example that draws the route polyline on the map view and adds markers on top of each stop location.

    GoogleMap googleMap = … // Instance of the Map view you are using
    ImmutableList<RouteToVehicleStop> route = event.newRoute();

    PolylineOptions routePolyline = new PolylineOptions().color(Color.BLUE);
    for (RouteToVehicleStop stop : route) {
        routePolyline.addAll(stop.path());

        MarkerOptions marker =
            new MarkerOptions().position(stop.vehicleStop().getWaypoint().getPosition());
        googleMap.addMarker(marker);
    }

    googleMap.addPolyline(routePolyline);
}

Screenshot showing image of a route overview

This results in a view similar to the screenshot to the right:

Step 5 - Get a route snapshot

If you want your app to issue a one-time call to retrieve a snapshot of the current route information, you can use the following method to retrieve that data:

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

You can do this instead of subscribing to route updates via event listeners.

Step 6 - Clean up

If your app no longer needs the route overview functionality, you should ensure you have cleaned up. Doing cleanup avoids unnecessary memory, processing, and network consumption in your application.

Remove a specific event listener

You should remove an event listener when a specific listener is no longer necessary.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Clear all event listeners

As part of your cleanup routine you can remove all the different event listeners registered at once.

vehicleRouteOverview.clearEventListeners();

Clear Route Overview API instance

Whenever Route Overview is no longer needed or the id of the vehicle being tracked has changed, you may call this API to clear internal references.

vehicleRouteOverview.clearInstance();