Calculating a reachable range

Project setup

Configure the project as described in the Project setup guide.

Then add the following dependencies to the build.gradle.kts file of your application module and synchronize the project.

1implementation("com.tomtom.sdk.routing:model:1.20.0")
2implementation("com.tomtom.sdk.routing:range-calculator-online:1.20.0")
3implementation("com.tomtom.sdk.location:model:1.20.0")
4implementation("com.tomtom.sdk.vehicle:model:1.20.0")
5implementation("com.tomtom.quantity:quantity:1.20.0")

The OnlineRangeCalculatorFactory can be used to create a RangeCalculator, which is the entry point for performing reachable range requests.

val rangeCalculator = OnlineRangeCalculatorFactory.create(applicationContext, "YOUR_TOMTOM_API_KEY")

Setting up range options

Range calculation is the generation of a polygon denoting the area reachable by a vehicle given a certain budget. It uses criteria that are very similar to route planning: the RangeCalculationOptions class. You can take advantage of named parameters in Kotlin to set only the properties that you need. The required parameters are the origin point and a budget.

The origin point is passed as an ItineraryPoint which can contain a heading in addition to the current coordinates.

The API allows the request of a range for more than one budget of the same type at a time; however, only a single budget is currently supported. It can be of the following budget types:

• Distance which results in a range based on the specified travel distance.
• Time which results in a range based on the specified travel time (isochrone).
• Fuel which results in a combustion vehicle range based on the specified fuel volume. To use this option, you must select a vehicle with a combustion engine in the range calculation options.
• Energy which results in an electric vehicle range based on the specified battery charge. To use this option, you must select a vehicle with an electric engine in the range calculation options.

There are several optional parameters that you can use to shape the range calculation criteria to fit your use cases. For a detailed description of the available parameters, see our Range API documentation.

You can specify a cost model which results in a range that is achievable using routes of that type. In particular, fast routes incur a greater energy consumption, leading to a shorter range when compared to short or efficient routes.

1val amsterdam = ItineraryPoint(Place(GeoPoint(52.377956, 4.897070)))
2
3val vehicle = Vehicle.Car(
4    electricEngine = ElectricEngine(
5        consumption = ElectricVehicleConsumption(
6            speedConsumption = mapOf(
7                Speed.kilometersPerHour(50) to ElectricConsumption.kilowattHoursPer100Kilometers(6.5),
8                Speed.kilometersPerHour(100) to ElectricConsumption.kilowattHoursPer100Kilometers(7),
9            ),
10        ),
11    ),
12)
13
14val rangeCalculationOptions = RangeCalculationOptions(
15    origin = amsterdam,
16    budgets = setOf(Budget.Energy(Energy.kilowattHours(5.0))),
17    vehicle = vehicle,
18)

Requesting ranges

Once you have a RangeCalculationOptions object, provide it to the calculateRange method. The range calculation call can be done either synchronously or asynchronously using a callback.

Synchronous calls

This call is blocking, meaning that the call to calculateRange blocks the program flow until the result or failure occurs. The response to the request is packed in the Result<Range, RoutingFailure> class. Use the Result.isSuccess() method to check if the call succeeded. If the method returns true, you can get the Range object using the Result.value() method. If an error occurred, Result.isFailure() returns true instead. More details about the error can be found using Result.failure().

1val amsterdam = ItineraryPoint(Place(GeoPoint(52.377956, 4.897070)))
2
3val vehicle = Vehicle.Car(
4    electricEngine = ElectricEngine(
5        consumption = ElectricVehicleConsumption(
6            speedConsumption = mapOf(
7                Speed.kilometersPerHour(50) to ElectricConsumption.kilowattHoursPer100Kilometers(6.5),
8                Speed.kilometersPerHour(100) to ElectricConsumption.kilowattHoursPer100Kilometers(7),
9            ),
10        ),
11    ),
12)
13
14val rangeCalculationOptions = RangeCalculationOptions(
15    origin = amsterdam,
16    budgets = setOf(Budget.Energy(Energy.kilowattHours(0.1))),
17    vehicle = vehicle,
18)
19
20when (val calculateRangeResult = rangeCalculator.calculateRange(rangeCalculationOptions)) {
21    is Result.Success -> calculateRangeResult.value()
22    is Result.Failure -> calculateRangeResult.failure()
23}

Asynchronous calls

The asynchronous call requires the Callback<Range, RoutingError> to be provided as a parameter to the request. If the call is successful, the callback’s onSuccess(result: Range) method is triggered with the routing result. If a failure occurred, it is provided by the callback’s onFailure(error: RoutingFailure) method.

1val amsterdam = ItineraryPoint(Place(GeoPoint(52.377956, 4.897070)))
2
3val rangeCalculationOptions = RangeCalculationOptions(
4    origin = amsterdam,
5    budgets = setOf(Budget.Distance(Distance.meters(1000))),
6)
7
8rangeCalculator.calculateRange(
9    rangeCalculationOptions,
10    object : Callback<Range, RoutingFailure> {
11        override fun onSuccess(result: Range) {
12            // YOUR CODE GOES HERE
13        }
14
15        override fun onFailure(failure: RoutingFailure) {
16            // YOUR CODE GOES HERE
17        }
18    },
19)

Setting the cost model and vehicle

Refer to the Route planning guide to learn about the cost model, such as route type and avoids, as well as available vehicle options.

Calculation failures

A RoutingFailure is returned if any failure occurred during the range calculation. For more information, refer to the Route planning failures documentation.

Next steps

Since you have learned how to calculate a range, here are recommendations for the next steps:

• Planning routes
• Showing polygons on the map