Route Consumption

Route consumption calculation is a beta feature which allows the consumption of fuel resources such as gasoline or electricity to be calculated for a given, already calculated route.

Vehicles have a limited range depending on the amount of fuel remaining and how much fuel the vehicle consumes per kilometer under different driving conditions. This is especially important for electric vehicles which can typically travel less distance on a full charge than a gasoline powered vehicle could travel on a full tank.

In order to ensure that a vehicle is able to complete a calculated route, SDK for Android can calculate the consumption for each element in that route given certain consumption parameters. This allows the developer to determine how much fuel the vehicle will have left at the end of the route on the one hand and, on the other hand, check where the vehicle would run out of fuel in case if the final destination is unreachable.

Since different vehicles consume different types of fuel (such as gasoline and electricity) and also have different rates of consumption, the consumption calculation must be configured with consumption parameters for a given vehicle before the calculation is performed.

An important concept for consumption calculation is the capacity unit. The capacity unit is how fuel is measured for a given vehicle. Because consumption calculation is general, the unit is effectively defined by the developer. For an electric vehicle the capacity unit is generally kilowatt hours (kWh), for a gasoline powered vehicle it could be liters of gasoline.

A vehicle will have a maximum capacity and current capacity indicating how much fuel it can hold in total and the current amount respectively.

In the following description we will assume that we are calculating consumption for an electric vehicle since this is the most common use case. The capacity unit used will be kilowatt hours (kWh).

The consumption parameters are grouped onto the ConsumptionParameters class. The API documentation provides descriptions of each of the individual values that can be modified. Here we will describe the more complex and important values. In order to begin, we'll create an empty consumption parameters object

ConsumptionParameters consumptionParams = new ConsumptionParameters();

The speed consumption table is the basis for most consumption calculations. It is stored as a table represented as a list of ConsumptionForSpeed objects. The table represents the consumption of the vehicle per meter in kilowatt hours (the capacity unit) for ranges of speeds.

Consider a very simple example with three ranges of speeds and consumption for each.

From this table we see that our vehicle consumes 38.82 kWh of capacity per meter when traveling between 0 and 30 km/h, 18.20 kWh of capacity per meter when traveling between 31 and 90 km/h and 27.41 kWh of capacity per meter when traveling at 90 km/h or faster. Of course this example is very simple, a real world speed consumption table would have finer grained values.

To use this table in our consumption parameters, call setSpeedParameters(List<ConsumptionForSpeed>) method with the upper bound of each range as the key and the consumption per meter as the value. The last range (for > 90 km/h) should use the key 250.

List<ConsumptionForSpeed> consumptionSpeed = new ArrayList<ConsumptionForSpeed>();
consumptionSpeed.add(new ConsumptionForSpeed(30, 38.82));
consumptionSpeed.add(new ConsumptionForSpeed(90, 18.20));
consumptionSpeed.add(new ConsumptionForSpeed(250, 27.41));

consumptionParams.setSpeedParameters(consumptionSpeed);

The speed consumption table is enough to calculate simplistic consumption for a route. Assuming that we already have a Route object called route which contains a calculated route calculate the consumption for this route.

RouteConsumption consumption =
  route.getConsumption(consumptionParameters, null);

Once we have the route consumption we can determine the last reachable position on the same route given current capacity of our vehicle. In this example we'll suppose that our vehicle has 100,000 kWh of remaining capacity at the beginning of the route.

GeoCoordinates lastPosition =
  route.getLastReachablePosition(consumption, 100000);

The variable lastPosition will now contain the last point that our vehicle will be able to reach before the capacity reaches zero. If the final destination of the route is reachable, lastPosition will be nil.

We can also use route consumption to obtain the consumption for each route element that the route comprises. The following code snippet prints out the starting and ending geo-coordinates for each route element as well as the consumption for that route element.

List<RouteElement> routeElements = route.getRouteElements().getElements();
  for (int i = 0; i < routeElements.size(); i++) {
    RouteElement element = routeElements.get(i);
    List<GeoCoordinate> geometry = element.getGeometry();
    double startLat = geometry.get(0).getLatitude();
    double startLong = geometry.get(0).getLongitude();
    double endLat = geometry.get(geometry.size() - 1).getLatitude();
    double endLong = geometry.get(geometry.size() - 1).getLongitude();
    Log.d(TAG, String.format("Route element (%.4f, %.4f) ---> (%.4f, %.4f) consumption %d",
startLat, startLong, endLat, endLong, consumption.getConsumption(i)));
  }

As mentioned above setting only consumptionSpeed property is sufficient for basic consumption calculation. There are more specific values which can be set to more closely model the consumption of a real vehicle across different road and traffic conditions. For more details on these properties please see the API documentation.