Quickstart
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.20.1")
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_TOMTOM_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 HERE9 }1011 override fun onFailure(failure: RoutingFailure) {12 // YOUR CODE GOES HERE13 }1415 override fun onRoutePlanned(route: Route) {16 // YOUR CODE GOES HERE17 }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.
Next steps
Since you have learned the basics of routing, here are recommendations for the next steps: