Calculating a reachable range
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 an isochrone based on the specified travel time.Fuel
which results in a combustion vehicle range based on the specified fuel volume. To use this option, you must select avehicle
with acombustion 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 avehicle
with anelectric 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)))23val vehicle = Vehicle.Car(4 electricEngine = ElectricEngine(5 consumption = ElectricVehicleConsumption(6 speedConsumption = mapOf(7 Speed.kilometersPerHour(50.0) to ElectricConsumption.kilowattHoursPer100Kilometers(6.5),8 Speed.kilometersPerHour(100) to ElectricConsumption.kilowattHoursPer100Kilometers(7)9 )10 )11 )12)1314val rangeCalculationOptions = RangeCalculationOptions(15 origin = amsterdam,16 budgets = setOf(Budget.Energy(Energy.kilowattHours(5.0))),17 vehicle = vehicle18)
Requesting ranges
Once you have a RangeCalculationOptions
object, provide it to the calculateRange
method. This can be done either synchronously or asynchronously using a callback
. The synchronous call blocks and returns a RangeCalculationResult
on success or a RangeCalculationFailure
on failure. If an asynchronous range calculation is successful, the onSuccess(RangeCalculationResult)
method is called; if a failure occurred, onFailure(RangeCalculationFailure)
is called.
1val amsterdam = ItineraryPoint(Place(GeoPoint(52.377956, 4.897070)))23val rangeCalculationOptions = RangeCalculationOptions(4 origin = amsterdam,5 budgets = setOf(Budget.Distance(Distance.meters(1000)))6)78rangeCalculator.calculateRange(9 rangeCalculationOptions,10 object : Callback<RangeCalculationResult, RangeCalculationFailure> {11 override fun onSuccess(result: RangeCalculationResult) {12 /* YOUR CODE GOES HERE */13 }1415 override fun onFailure(failure: RangeCalculationFailure) {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 RangeCalculationFailure
instance is returned if any failure occurred during the range calculation. This object contains a RoutingFailure
describing the root cause. 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: