Calculating a reachable range

VERSION 0.66.0

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 struct. You can take advantage of named parameters in Swift to set only the properties that you need. The required parameters are the origin point and RangeCalculationOptions.budgets.

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

The API allows requesting 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:

Budget.distance(length:), which results in a range based on the specified travel distance.
Budget.time(duration:), which results in an isochrone based on the specified travel time.
Budget.fuel(volume:), which results in a combustion vehicle range based on the specified fuel volume. To use this option, you must select a Vehicle with a CombustionEngine in the range calculation options.
Budget.energy(amount:), which results in an electric vehicle range based on the specified battery charge. To use this option, you must select a Vehicle with an ElectricEngine 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 CostModel, which results in a range that is achievable using routes of that type. In particular, RouteType.fast routes incur a greater consumption, leading to a smaller range when compared to RouteType.short or RouteType.efficient routes.

1let amsterdam = ItineraryPoint(coordinate: CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070))
2
3let electricSpeedConsumption: [Measurement<UnitSpeed>: Measurement<TTUnitElectricEfficiency>] = [
4    Measurement.tt.kilometersPerHour(50.0): Measurement.tt.kilowattHoursPer100Kilometers(6.5),
5    Measurement.tt.kilometersPerHour(100): Measurement.tt.kilowattHoursPer100Kilometers(7),
6]
7
8let options: RangeCalculationOptions
9do {
10    let electricVehicleConsumption = try ElectricEngine.Consumption(speedConsumption: electricSpeedConsumption)
11    options = try RangeCalculationOptions(
12        origin: amsterdam,
13        budgets: [.energy(amount: Measurement.tt.kilowattHours(5.0))],
14        vehicle: Car(electricEngine: ElectricEngine(consumption: electricVehicleConsumption))
15    )
16} catch {
17    print("Invalid range calculation options: \(error.localizedDescription)")
18    return
19}

Requesting ranges

Once you have a RangeCalculationOptions object, create an instance of RangeCalculator using OnlineRangeCalculatorFactory.create(apiKey:baseURL:) and pass the RangeCalculationOptions object to RangeCalculator.calculateRange(options:completion:) method. The result of the range calculation is passed into the completion block passed to the RangeCalculator.calculateRange(options:completion:) method. The result can be either Result.success(_:) with range if the calculation succeeded, or Result.failure(_:) if the calculation failed.

1let amsterdam = ItineraryPoint(coordinate: CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070))
2let combustionSpeedConsumption: [Measurement<UnitSpeed>: Measurement<UnitFuelEfficiency>] = [
3    Measurement.tt.kilometersPerHour(50.0): Measurement.tt.litersPer100Kilometers(6.5),
4    Measurement.tt.kilometersPerHour(100): Measurement.tt.litersPer100Kilometers(7),
5]
6
7let options: RangeCalculationOptions
8do {
9    let combustionVehicleConsumption = try CombustionEngine.Consumption(speedConsumption: combustionSpeedConsumption)
10    options = try RangeCalculationOptions(
11        origin: amsterdam,
12        budgets: [.energy(amount: Measurement.tt.kilowattHours(0.1))],
13        vehicle: Car(combustionEngine: CombustionEngine(consumption: combustionVehicleConsumption))
14    )
15} catch {
16    print("Invalid range calculation options: \(error.localizedDescription)")
17    return
18}
19
20rangeCalculator.calculateRange(options: options) { result in
21    switch result {
22    case let .success(response):
23        if response != nil {
24            // success case
25        }
26    case .failure:
27        // failure case
28        break
29    }
30}

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 errors

If any errors occur during range calculation, the result returned by the completion block will be Result.failure(_:). RoutingError will be returned for routing-specific errors.

For more information, refer to the Planning errors.

Next steps

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