Calculating a reachable range

VERSION 0.71.1

Introduction

The Reachable Range API calculates how far a vehicle can travel from a given point, based on constraints such as distance, time, fuel, or battery charge. This is useful in applications supporting electric or combustion vehicles, delivery logistics, and travel-time-based decisions.

A successful range calculation returns a Range object containing a polygon that represents the reachable area under the selected constraints. You can render this polygon as an overlay on the map to visually communicate travel limits.

To learn how to display the range polygon on the map, see the Map overlays guide.

Setting up range options

To perform a range calculation, define the input using the RangeCalculationOptions struct. It requires two key parameters: the origin point and RangeCalculationOptions.budgets.

You can use named parameters in Swift to set only the properties you need. The origin point is passed as an ItineraryPoint, which can include a heading along with the current coordinates.

While the API supports specifying multiple budgets of the same type, currently, only one budget is supported per request. The budget can be one of the following Budget types:

Budget.distance(length:) — calculates the range based on a specified travel distance.
Budget.time(duration:) — calculates the range based on a specified travel time (isochrone).
Budget.fuel(volume:) — calculates the range for a combustion vehicle based on the specified fuel volume. To use this option, provide a Vehicle with a CombustionEngine in the range options.
Budget.energy(amount:) — calculates the range for an electric vehicle based on the specified battery charge. To use this option, provide a Vehicle with an ElectricEngine in the range options.

You can customize the range calculation further with several optional parameters. For more details, see the official Range API documentation.

You can specify a CostModel, which results in a range that is achievable using routes of that type. For example, RouteType.fast routes incur 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 a RangeCalculator instance using OnlineRangeCalculatorFactory.create(apiKey:baseURL:). Then pass the options to the RangeCalculator.calculateRange(options:completion:) method. The method returns the result asynchronously through the completion block. It will be either: * Result.success(_:) — contains a Range if the calculation succeeds. * Result.failure(_:) — contains an error if the calculation fails.

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 more about configuring the cost model, including route type, avoid options, and vehicle settings.

Calculation errors

If an error occurs during range calculation, the result returned by the completion block will be Result.failure(_:). For routing-specific issues, the error will be a RoutingError.

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: