Quickstart

VERSION 1.0.0

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 setup

Configure the project as described in the Project setup guide.

Then add the following dependencies to the build.gradle.kts file of your application module and synchronize the project.

implementation("com.tomtom.sdk.routing:route-planner-online:1.0.0")

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 RoutePlanningResponse 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: RoutePlanningResponse) method is triggered with the routing result. If a failure occurred, it is provided by the callback’s onFailure(failure: RoutingFailure) 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: RoutePlanningResponse) {
8            /* YOUR CODE GOES HERE */
9        }
10
11        override fun onFailure(failure: RoutingFailure) {
12            /* YOUR CODE GOES HERE */
13        }
14
15        override fun onRoutePlanned(route: Route) {
16            /* YOUR CODE GOES HERE */
17        }
18    }
19)

Incremental guidance computation

The mode for guidance computation is controlled by RouteInformationMode. It contains two cases: Complete and FirstIncrement.

The FirstIncrement is faster method, it delivers only the first guidance increment. This guidance increment contains one or more potentially combinable instructions and the corresponding lane guidance.

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<Range, RoutingFailure> class. Use the Result.isSuccess() method to check if the call succeeded. If the method returns true, you can get the Range 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<Range, RoutingError> to be provided as a parameter to the request. If the call is successful, the callback’s onSuccess(result: Range) method is triggered with the routing result. If a failure occurred, it is provided by the callback’s onFailure(error: RoutingFailure) 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<Range, RoutingFailure> {
11        override fun onSuccess(result: Range) {
12            /* YOUR CODE GOES HERE */
13        }
14
15        override fun onFailure(failure: RoutingFailure) {
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: