Quickstart

VERSION 0.3.34
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-client-online:0.3.34"
    3}

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

val routingApi = OnlineRoutingApi.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<RoutingResult, RoutingException> class. Use the Result.isSuccess() method to check if the call succeeded. If the method returns true, you can get the RoutingResult 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 = GeoCoordinate(52.377956, 4.897070)
2val rotterdam = GeoCoordinate(51.926517, 4.462456)
3val routingOptions = RoutingOptions(itinerary = Itinerary(amsterdam, rotterdam))
4val result = routingApi.planRoute(routingOptions)
5when (result) {
6 is Result.Success -> result.failure()
7 is Result.Failure -> result.value()
8}

Asynchronous calls

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

1val amsterdam = GeoCoordinate(52.377956, 4.897070)
2val rotterdam = GeoCoordinate(51.926517, 4.462456)
3val routingOptions = RoutingOptions(itinerary = Itinerary(amsterdam, rotterdam))
4routingApi.planRoute(
5 routingOptions,
6 object : RoutingCallback {
7 override fun onSuccess(result: RoutingResult) {
8 /* YOUR CODE GOES HERE */
9 }
10
11 override fun onError(error: RoutingError) {
12 /* YOUR CODE GOES HERE */
13 }
14 }
15)

Route with alternatives