SDK for iOS Developer's Guide

Route Consumption

Route consumption calculation is a beta feature which allows the consumption of fuel to be calculated for a given, already calculated route.


To ensure that a vehicle is able to complete a calculated route, SDK for iOS can calculate the consumption for each element in that route given certain consumption parameters. This allows the developer to, firstly, determine how much fuel the vehicle will have left at the end of the route and, secondly, check where vehicle would run out of fuel in case if the final destination is not reachable.




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 NMARouteConsumptionParameters 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. To begin with, we'll create an empty consumption parameters object.

NMARouteConsumptionParamters *consumptionParams = [[NMARouteConsumptionParameters alloc] init];

The speed consumption table is the basis for most of the consumption calculation. It is stored in consumptionSpeed property. The table represents consumption of the vehicle per metre in kilowatt hours (the capacity unit) for ranges of speeds.


Table 1.
Speed range (km/h) Consumption per metre (kWh)
0 - 30 38.82
31 - 90 18.20
> 90 27.41

From this table we see that our vehicle consumes 38.82 kWh of capacity per metre when travelling between 0 and 30 km/h, 18.20 kWh of capacity per metre when travelling between 31 and 90 km/h, and 27.41 kWh of capacity per metre when travelling 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, we set consumptionSpeed property using the upper bound of each range as the key and the consumption per metre as the value. The final range (for > 90 km/h) should use the key 250.

consumptionParams.consumptionSpeed = @{ @(30):  @(38.82),
          @(90):  @(18.20),
          @(250): @(27.41) };

The speed consumption table is enough to calculate simplistic consumption for a route, so let's look at how to do that. Let's assume that we already have an NMARoute object called route which contains a calculated route. Now let's calculate the consumption for this route.

NMARouteConsumption *consumption =
  [route consumptionWithParameters:consumptionParams

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.

NMAGeoCoordinates *lastPosition =
  [route lastReachablePositionWithConsumption:consumption

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


[route.routeElements enumerateObjectsUsingBlock:^(NMARouteElement *element, NSUInteger idx, BOOL *stop) {
    if (idx >= [consumption firstAvailableConsumptionIndex] && [element.geometry count] > 0) {
      NSInteger elementConsumption = [consumption getConsumptionWithIndex:idx];
      NSLog(@"Route element (%.4f, %.4f) --> (%.4f, %.4f) consumption: %zd",
          element.geometry.firstObject.latitude, element.geometry.firstObject.longitude,
          element.geometry.lastObject.latitude, element.geometry.lastObject.longitude,

As mentioned above, setting only consumptionSpeed property is sufficient for basic consumption calculation. There are more specialised 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.