# Calculating a reachable range

VERSION 0.12.0
PUBLIC PREVIEW

## 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:

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 ranges 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.0) 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 = 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)))2
3val rangeCalculationOptions = RangeCalculationOptions(4    origin = amsterdam,5    budgets = setOf(Budget.Distance(Distance.meters(1000)))6)7
8rangeCalculator.calculateRange(9    rangeCalculationOptions,10    object : Callback<RangeCalculationResult, RangeCalculationFailure> {11        override fun onSuccess(result: RangeCalculationResult) {12            /* YOUR CODE GOES HERE */13        }14
15        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: