Quickstart

VERSION 0.3.1106
PUBLIC PREVIEW

The Routing module provides the tools to integrate the TomTom Routing API into an Android application. It is used to calculate a route between an origin and a destination, using a range of options and taking traffic into account. Read more about TomTom’s Routing parameters.

Once planned, routes can be displayed on the map or used for turn by turn navigation.

Project set up

To use the Routing module, you will need to do the following:

  1. Get your TomTom API key from the Developer Portal. You can find instructions on how to do this at the How do I get a TomTom API Key? page.
  2. Configure the project as described in the Project setup guide.
  3. Once the project is set up, add the Routing module dependency in the app module’s build.gradle.
    1dependencies {
    2 implementation "com.tomtom.sdk.routing:route-planner-online:0.3.1106"
    3}

After synchronizing the project, you can initialize the RoutePlanner object. It is the entry point for performing routing requests. The RoutePlanner object is initialized using the OnlineRoutePlanner class.

val routePlanner = OnlineRoutePlanner.create(applicationContext, "YOUR_API_KEY")

Making routing calls

The routing call can be done either synchronously or asynchronously.

Synchronous calls

Synchronous calls are useful when you want to have full control over the threading model used in your application. Note that routing calls block execution, so they must be done off the main thread. Otherwise, an exception is thrown.

The response to the request is packed in the Result<RoutePlanningResult, RoutingError> class. Use the Result.isSuccess() method to check if the call succeeded. If the method returns true, you can get the RoutePlanningResult 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 = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = RoutePlanningOptions(itinerary = Itinerary(amsterdam, rotterdam))
4val result = routePlanner.planRoute(routePlanningOptions)
5when (result) {
6 is Result.Success -> result.failure()
7 is Result.Failure -> result.value()
8}

Asynchronous calls

The asynchronous call requires the RoutePlanningCallback to be provided as a parameter to the request. If the call is successful, the callback’s onSuccess(result: RoutePlanningResult) method is triggered with the routing result. If an error occurred, it is provided by the callback’s onError(error: RoutingError) method.

1val amsterdam = GeoPoint(52.377956, 4.897070)
2val rotterdam = GeoPoint(51.926517, 4.462456)
3val routePlanningOptions = RoutePlanningOptions(itinerary = Itinerary(amsterdam, rotterdam))
4routePlanner.planRoute(
5 routePlanningOptions,
6 object : RoutePlanningCallback {
7 override fun onSuccess(result: RoutePlanningResult) {
8 /* YOUR CODE GOES HERE */
9 }
10
11 override fun onError(error: RoutingError) {
12 /* YOUR CODE GOES HERE */
13 }
14
15 override fun onRoutePlanned(route: Route) {
16 /* YOUR CODE GOES HERE */
17 }
18 }
19)

Route with alternatives

Making range calls

The range calculation call can be done either synchronously or asynchronously.

Synchronous calls

The response to the request is packed in the Result<RangeCalculationResult, RoutingError> class. Use the Result.isSuccess() method to check if the call succeeded. If the method returns true, you can get the RangeCalculationResult 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 combustionCar = Vehicle.Car(
4 combustionEngine = CombustionEngine(
5 consumption = CombustionVehicleConsumption(
6 speedConsumption = mapOf(
7 Speed.kilometersPerHour(50.0) to FuelConsumption.litersPer100Kilometers(6.5),
8 Speed.kilometersPerHour(100) to FuelConsumption.litersPer100Kilometers(7)
9 )
10 )
11 )
12)
13
14val rangeCalculationOptions = RangeCalculationOptions(
15 origin = amsterdam,
16 budgets = setOf(Budget.Energy(Energy.kilowattHours(0.1))),
17 vehicle = combustionCar
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<RangeCalculationResult, RoutingError> to be provided as a parameter to the request. If the call is successful, the callback’s onSuccess(result: RangeCalculationResult) method is triggered with the routing result. If an error occurred, it is provided by the callback’s onError(error: RangeCalculationError) 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<RangeCalculationResult, RangeCalculationError> {
11 override fun onSuccess(result: RangeCalculationResult) {
12 /* YOUR CODE GOES HERE */
13 }
14
15 override fun onError(error: RangeCalculationError) {
16 /* YOUR CODE GOES HERE */
17 }
18 }
19)

Next steps

Since you have learned the basics of routing, here are recommendations for the next steps: