HERE SDK for Android (Starter Edition)

HERE Android SDK Developer's Guide

Route Calculation for Walking or Driving

HERE Android SDK supports route calculation with multiple waypoints optimized for walking or driving.

A route describes a path between at least two waypoints, the starting point and the destination, with optional intermediate waypoints in between. Applications can provide route information to users in two ways:

  • A line rendered on a map that displays a connecting path between all waypoints
  • Turn-by-turn directions in text format
  • To use this feature, your application must include the Gson library (release 2.2.4 or a compatible version) on its class path.
  • To support routes that are greater than 5000 km, add the largeHeap attribute in the <Application> section of AndroidManifest.xml. For more information see this article on managing your app memory.

Route Calculation Classes

This section introduces the following classes that are used for route calculations:
  • RouteManager
  • RoutePlan
  • RouteOptions

The RouteManager class is responsible for calculating a route. An application can initiate a route calculation by calling RouteManager.calculateRoute(RoutePlan, Listener) method providing options and waypoints through RoutePlan and receive progress updates through the RouteManager.Listener instance.

RoutePlan is a waypoint container that is used for route calculation. A RoutePlan object is comprised of a list of waypoint objects and optional RouteOptions. If RouteOptions are not specified, default values are used. You can add an individual waypoint to a RoutePlan by using a GeoCoordinate.

The RouteOptions class is a model of parameters required to calculate one route. It encapsulates "building block" parameters for a route such as:

  • The desired number of routes
  • The direction of travel that the route should start in
  • The routing type such as fastest travel time or shortest distance
  • The mode of transportation, e.g. by walking or driving
  • The departure time
  • The allowed types of route segments such as dirt roads, highways, or ferries
Note: Routing type describes different optimizations that can be applied during the route calculation:
  • Fastest - route calculation from start to destination optimized by travel time. In some cases the route returned by the fastest mode may not be the route with the shortest possible travel time. For example, it may favor a route that remains on a highway even if a shorter travel time can be achieved by taking a detour or shortcut through a side road.
  • Shortest - route calculation from start to destination disregarding any speed information. In this mode the distance of the route is minimized while keeping the route sensible. This includes, for example, penalizing turns. Because of that the resulting route will not necessarily be the one with minimal distance.
  • Balanced - route calculation from start to destination optimized based on combination of travel time and distance.

HERE SDK supports alternate routes between two waypoints. The alternate route feature allows more than one route to be returned after a route calculation. You can use the RouteOptions class to set the desired number of routes, HERE SDK then returns different routes according to this limit. Note that the first element of the returned list of RouteResult is the main route, and the rest of the returned routes are not listed in any specific order.

RouteResult and Route

The RouteResult class represents a route calculation result. Applications can retrieve a Route object and the corresponding set of violated routing conditions. Violated routing options are the conditions that a routing result was unable to adhere to. For example, after specifying a route calculation that avoids tolls and ferries, you may get a RouteResult that contains a Route object along with RouteResult.ViolatedOption.AVOID_TOLL_ROADS. This indicates that although a route was found, this route goes through at least one toll road — violating a condition of your route request.

The Route class is a distinct calculated path connecting two or more waypoints consisting of a list of maneuvers and route links. By using RouteManager.calculateRoute(RoutePlan, Listener) to trigger a route calculation your application can use the RouteManager.Listener to monitor the calculation and trigger callback methods. These callback methods have parameters that include a list of the calculated RouteResult objects. Using these RouteResult objects you can call getRoute() to retrieve the routes.

The MapRoute Class

The MapRoute class is a type of MapObject that displays a calculated route on a map. Typically, an application creates a MapRoute after a route calculation passing the relevant Route object as a parameter to the MapRoute(Route) constructor before adding the MapRoute to the map by calling Map.addMapObject(MapRoute).

For example, if you want to render a route that connects two waypoints (start and destination), you can add the following application logic:

Figure 1. Calculate Route
  1. Declare a RouteManager instance.
    // Declare the rm variable (the RouteManager)
    RouteManager rm = new RouteManager();
  2. Create a RoutePlan and add two GeoCoordinate waypoints.
    // Create the RoutePlan and add two waypoints
    RoutePlan routePlan = new RoutePlan();
    routePlan.addWaypoint(new GeoCoordinate(49.1966286, -123.0053635));
    routePlan.addWaypoint(new GeoCoordinate(49.1947289, -123.1762924));
  3. Create a new RouteOptions object, set its Type and TransportMode values by calling appropriate RouteOptions methods, and then add it to RoutePlan.
    // Create the RouteOptions and set its transport mode & routing type
    RouteOptions routeOptions = new RouteOptions();
  4. To make sure route calculation can handle returning a Route object that in turn can be used to create a MapRoute instance for rendering on the map, add an inner class by implementing RouteManager.Listener in the appropriate activity class.
    private class RouteListener implements RouteManager.Listener {
      // Method defined in Listener
      public void onProgress(int percentage) {
        // Display a message indicating calculation progress
      // Method defined in Listener
      public void onCalculateRouteFinished(RouteManager.Error error, List<RouteResult> routeResult) {
        // If the route was calculated successfully
        if (error == RouteManager.Error.NONE) {
          // Render the route on the map
          MapRoute mapRoute = new MapRoute(routeResult.get(0).getRoute());
        else {
          // Display a message indicating route calculation failure
  5. After adding the inner listener class (named RouteListener for this example) calculate the route by calling RouteManager.calculateRoute(RoutePlan, Listener) (making use of an instantiated RouteListener object).
    // Calculate the route
    rm.calculateRoute(routePlan, new RouteListener());
Note: Routes with more than 100 waypoints may require significant calculation time.

Routing-related Enumerations

Route calculations make use of HERE SDK enumerations that include:

  • The Route.TrafficPenaltyMode enum - represents values describing how the RouteManager should handle traffic events in a route calculation such as DISABLED, AVOID_LONG_TERM_CLOSURES, or OPTIMAL
  • The RouteOptions.Type enum - represents values describing different routing types such as FASTEST, SHORTEST, or ECONOMIC
  • The RouteOptions.TransportMode enum - represents values describing different transport modes such as CAR or PEDESTRIAN
  • The RouteManager.Error enum - represents values describing possible route calculation errors, such as NONE or VIOLATES_OPTIONS
  • The RouteResult.ViolatedOption enum - represents values describing possible route option violations such as AVOID_HIGHWAYS or AVOID_FERRIES