Route planning

The TripManager component handles all route planning operations in the Client Integration Library, including planning routes to destinations, managing waypoints, configuring routing preferences, and controlling the trip lifecycle.

Overview

TripManager provides functionality for:

Planning routes
Adding and removing waypoints
Configuring avoid preferences (tolls, ferries, motorways, etc.)
Canceling active trips
Starting navigation for the planned trip
Observing trip progress during navigation
Retrieving route polyline

Planning a basic trip

To plan a simple route to a destination, use the planTrip method with TripPlanningParameters.ToDestination:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.NavigableLocation
3import com.tomtom.automotive.integration.client.api.trip.TripManager
4import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningCallback
5import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningFailure
6import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningParameters
7import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningResponse
8import com.tomtom.automotive.integration.client.api.model.trip.Trip
9import com.tomtom.automotive.integration.client.common.Callback
10import com.tomtom.automotive.integration.client.common.Result
11import com.tomtom.automotive.integration.client.common.SdkReleasable
12
13private val TAG = "TripPlanning"
14private var planTripReleasable: SdkReleasable? = null
15private var currentTrip: Trip? = null
16
17fun planTrip(tripManager: TripManager, destination: NavigableLocation) {
18    val parameters = TripPlanningParameters.ToDestination(
19        destination = destination,
20        avoids = null,
21        waypoints = null
22    )
23
24    planTripReleasable = tripManager.planTrip(
25        tripPlanningParameters = parameters,
26        callback = object : TripPlanningCallback {
27            override fun onTripPlanned(response: Result<TripPlanningResponse, TripPlanningFailure>) {
28                when (response) {
29                    is Result.Success -> {
30                        val trip = response.value.trip
31                        Log.d(TAG, "Trip planned: ${trip.id}")
32                        currentTrip = trip
33                    }
34                    is Result.Failure -> {
35                        Log.e(TAG, "Error planning trip: ${response.failure}")
36                    }
37                }
38            }
39
40            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
41                Log.e(TAG, "Trip planning unavailable: ${reason.devMessage}")
42            }
43        }
44    )
45}

Planning with waypoints

For routes with multiple stops, include waypoints in your trip planning parameters:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.NavigableLocation
4import com.tomtom.automotive.integration.client.api.trip.TripManager
5import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningCallback
6import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningFailure
7import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningParameters
8import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningResponse
9import com.tomtom.automotive.integration.client.common.Callback
10import com.tomtom.automotive.integration.client.common.Result
11import com.tomtom.automotive.integration.client.common.SdkReleasable
12
13private val TAG = "TripPlanning"
14private var planTripReleasable: SdkReleasable? = null
15
16fun planTripWithWaypoints(
17    tripManager: TripManager,
18    destination: NavigableLocation,
19    waypoints: List<NavigableLocation>
20) {
21    val parameters = TripPlanningParameters.ToDestination(
22        destination = destination,
23        avoids = null,
24        waypoints = waypoints
25    )
26
27    planTripReleasable = tripManager.planTrip(
28        tripPlanningParameters = parameters,
29        callback = object : TripPlanningCallback {
30            override fun onTripPlanned(response: Result<TripPlanningResponse, TripPlanningFailure>) {
31                when (response) {
32                    is Result.Success -> {
33                        Log.d(TAG, "Trip with waypoints planned: ${response.value.trip.id}")
34                    }
35                    is Result.Failure -> {
36                        Log.e(TAG, "Error planning trip: ${response.failure}")
37                    }
38                }
39            }
40
41            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
42                Log.e(TAG, "Trip planning unavailable: ${reason.devMessage}")
43            }
44        }
45    )
46}
47
48// Example usage
49val waypoints = listOf(
50    NavigableLocation.Place(Coordinate(latitude = 52.3676, longitude = 4.9041), address = null),
51    NavigableLocation.Place(Coordinate(latitude = 52.5200, longitude = 13.4050), address = null)
52)

Waypoints are visited in the order they appear in the list.

Configuring route avoidances

Specify road types to avoid when planning a trip:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.NavigableLocation
3import com.tomtom.automotive.integration.client.api.model.trip.TripPlanningAvoids
4import com.tomtom.automotive.integration.client.api.trip.TripManager
5import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningCallback
6import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningFailure
7import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningParameters
8import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningResponse
9import com.tomtom.automotive.integration.client.common.Callback
10import com.tomtom.automotive.integration.client.common.Result
11
12private val TAG = "TripPlanning"
13
14fun planTripWithAvoidances(
15    tripManager: TripManager,
16    destination: NavigableLocation,
17    avoidTolls: Boolean,
18    avoidFerries: Boolean,
19    avoidMotorways: Boolean
20) {
21    val avoids = buildSet {
22        if (avoidTolls) add(TripPlanningAvoids.TOLLS)
23        if (avoidFerries) add(TripPlanningAvoids.FERRY)
24        if (avoidMotorways) add(TripPlanningAvoids.MOTORWAY)
25    }
26
27    val parameters = TripPlanningParameters.ToDestination(
28        destination = destination,
29        avoids = avoids.takeIf { it.isNotEmpty() },
30        waypoints = null
31    )
32
33    tripManager.planTrip(
34        tripPlanningParameters = parameters,
35        callback = object : TripPlanningCallback {
36            override fun onTripPlanned(response: Result<TripPlanningResponse, TripPlanningFailure>) {
37                when (response) {
38                    is Result.Success -> {
39                        Log.d(TAG, "Trip planned: ${response.value.trip.id}")
40                    }
41                    is Result.Failure -> {
42                        Log.e(TAG, "Error planning trip: ${response.failure}")
43                    }
44                }
45            }
46
47            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
48                Log.e(TAG, "Trip planning unavailable: ${reason.devMessage}")
49            }
50        }
51    )
52}

Available avoid options

The library supports the following avoidance preferences:

TripPlanningAvoids.TOLLS - Avoid toll roads
TripPlanningAvoids.MOTORWAY - Avoid highways
TripPlanningAvoids.FERRY - Avoid ferries
TripPlanningAvoids.UNPAVED_ROAD - Avoid unpaved roads
TripPlanningAvoids.BORDER_CROSSING - Avoid border crossings
TripPlanningAvoids.CARPOOLS - Avoid high occupancy vehicle roads
TripPlanningAvoids.TUNNELS - Avoid tunnels
TripPlanningAvoids.LOW_EMISSION_ZONES - Avoid low emission zones

Managing waypoints on active trips

Adding waypoints

Add intermediate stops to an active trip:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.NavigableLocation
3import com.tomtom.automotive.integration.client.api.model.trip.RouteStop
4import com.tomtom.automotive.integration.client.api.trip.TripManager
5import com.tomtom.automotive.integration.client.api.trip.waypoints.AddWaypointParameters
6import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsCallback
7import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsFailure
8import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsResponse
9import com.tomtom.automotive.integration.client.common.Callback
10import com.tomtom.automotive.integration.client.common.Result
11
12private val TAG = "TripPlanning"
13
14fun addWaypoint(tripManager: TripManager, location: NavigableLocation) {
15    val parameters = AddWaypointParameters(waypoint = location)
16
17    tripManager.addWaypoint(
18        params = parameters,
19        callback = object : UpdateWaypointsCallback {
20            override fun onWaypointsUpdated(response: Result<UpdateWaypointsResponse, UpdateWaypointsFailure>) {
21                when (response) {
22                    is Result.Success -> {
23                        val waypoints: List<RouteStop> = response.value.trip.itinerary.waypoints
24                        Log.d(TAG, "Waypoint added successfully. Total waypoints: ${waypoints.size}")
25                    }
26                    is Result.Failure -> {
27                        Log.e(TAG, "Failed to add waypoint: ${response.failure}")
28                    }
29                }
30            }
31
32            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
33                Log.e(TAG, "Add waypoint unavailable: ${reason.devMessage}")
34            }
35        }
36    )
37}

Removing waypoints

Remove a waypoint from the trip:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.trip.RouteStop
3import com.tomtom.automotive.integration.client.api.trip.TripManager
4import com.tomtom.automotive.integration.client.api.trip.waypoints.RemoveWaypointParameters
5import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsCallback
6import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsFailure
7import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsResponse
8import com.tomtom.automotive.integration.client.common.Callback
9import com.tomtom.automotive.integration.client.common.Result
10
11private val TAG = "TripPlanning"
12
13fun removeWaypoint(tripManager: TripManager, routeStop: RouteStop) {
14    val parameters = RemoveWaypointParameters(waypoint = routeStop)
15
16    tripManager.removeWaypoint(
17        params = parameters,
18        callback = object : UpdateWaypointsCallback {
19            override fun onWaypointsUpdated(response: Result<UpdateWaypointsResponse, UpdateWaypointsFailure>) {
20                when (response) {
21                    is Result.Success -> {
22                        Log.d(TAG, "Waypoint removed successfully")
23                    }
24                    is Result.Failure -> {
25                        Log.e(TAG, "Failed to remove waypoint: ${response.failure}")
26                    }
27                }
28            }
29
30            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
31                Log.e(TAG, "Remove waypoint unavailable: ${reason.devMessage}")
32            }
33        }
34    )
35}

Observing trip progress

Monitor navigation progress:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.trip.TripManager
3import com.tomtom.automotive.integration.client.api.trip.tripprogress.TripProgressInfo
4import com.tomtom.automotive.integration.client.api.trip.tripprogress.TripProgressListener
5import com.tomtom.automotive.integration.client.api.trip.tripprogress.TripProgressParameters
6import com.tomtom.automotive.integration.client.common.Callback
7import com.tomtom.automotive.integration.client.common.SdkReleasable
8
9private val TAG = "TripPlanning"
10private var tripProgressReleasable: SdkReleasable? = null
11
12fun observeTripProgress(tripManager: TripManager) {
13    tripProgressReleasable = tripManager.observeTripProgress(
14        tripProgressParameters = TripProgressParameters(),
15        tripProgressListener = object : TripProgressListener {
16            override fun onTripProgress(info: TripProgressInfo) {
17                Log.d(TAG, "Remaining distance: ${info.distanceRemaining.formattedValue?.formatted}")
18                Log.d(TAG, "Remaining time: ${info.remainingTime.formattedValue?.formatted}")
19                Log.d(TAG, "ETA: ${info.eta.formattedValue?.formatted}")
20            }
21
22            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
23                Log.e(TAG, "Trip progress unavailable: ${reason.devMessage}")
24            }
25        }
26    )
27}
28
29fun unObserveTripProgress() {
30    tripProgressReleasable?.release()
31    tripProgressReleasable = null
32}

Retrieving the route polyline

The route polyline represents the geometric path of a navigated route as a sequence of geographic coordinates. Each coordinate in the polyline contains latitude and longitude values in degrees.

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.quantity.Distance
4import com.tomtom.automotive.integration.client.api.trip.TripManager
5import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineCallback
6import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineFailure
7import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineParameters
8import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineResponse
9import com.tomtom.automotive.integration.client.common.Callback
10import com.tomtom.automotive.integration.client.common.Result
11import com.tomtom.automotive.integration.client.common.SdkReleasable
12
13private val TAG = "TripPlanning"
14private var routePolylineReleasable: SdkReleasable? = null
15
16fun getRoutePolyline(tripManager: TripManager) {
17    // Request 100 polyline points from current location to destination
18    val parameters = RoutePolylineParameters(
19        numberOfPolylinePoints = 100,
20        startOffset = null, // null means start from current location
21        endOffset = null    // null means end at the destination
22    )
23
24    routePolylineReleasable = tripManager.getRoutePolyline(
25        params = parameters,
26        callback = object : RoutePolylineCallback {
27            override fun onRoutePolyline(response: Result<RoutePolylineResponse, RoutePolylineFailure>) {
28                when (response) {
29                    is Result.Success -> {
30                        val polylinePoints: List<Coordinate> = response.value.upcomingPolylinePoints
31                        Log.d(TAG, "Received ${polylinePoints.size} polyline points")
32                        
33                        // Each coordinate contains latitude and longitude in degrees
34                        polylinePoints.forEach { coordinate ->
35                            Log.d(TAG, "Point: lat=${coordinate.latitude}, lon=${coordinate.longitude}")
36                        }
37                    }
38                    is Result.Failure -> {
39                        Log.e(TAG, "Failed to get route polyline: ${response.failure}")
40                    }
41                }
42            }
43
44            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
45                Log.e(TAG, "Route polyline unavailable: ${reason.devMessage}")
46            }
47        }
48    )
49}
50
51// Example: Get polyline for a specific segment of the route
52fun getRoutePolylineSegment(tripManager: TripManager) {
53    val parameters = RoutePolylineParameters(
54        numberOfPolylinePoints = 50,
55        startOffset = Distance.Companion.meters(1000.0), // Start 1km from route start
56        endOffset = Distance.Companion.meters(5000.0)    // End 5km from route start
57    )
58
59    tripManager.getRoutePolyline(params = parameters, callback = object : RoutePolylineCallback {
60        override fun onRoutePolyline(response: Result<RoutePolylineResponse, RoutePolylineFailure>) {
61            when (response) {
62                is Result.Success -> {
63                    Log.d(TAG, "Retrieved polyline segment with ${response.value.upcomingPolylinePoints.size} points")
64                }
65                is Result.Failure -> {
66                    Log.e(TAG, "Failed to get polyline segment: ${response.failure}")
67                }
68            }
69        }
70
71        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
72            Log.e(TAG, "Route polyline unavailable: ${reason.devMessage}")
73        }
74    })
75}

Polyline data structure

The RoutePolylineResponse contains:

upcomingPolylinePoints: A list of Coordinate objects representing the route geometry

Each Coordinate object provides:

latitude: The latitude in degrees (range: -90.0 to 90.0)
longitude: The longitude in degrees (range: -180.0 to 180.0)

The polyline points are ordered sequentially along the route from the start offset to the end offset. You can control the density of points by adjusting the numberOfPolylinePoints parameter, and specify which portion of the route to retrieve using the startOffset and endOffset parameters.

Canceling a trip

Stop an active navigation session:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.trip.TripManager
3import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripCallback
4import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripFailure
5import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripParameters
6import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripResponse
7import com.tomtom.automotive.integration.client.common.Callback
8import com.tomtom.automotive.integration.client.common.Result
9
10private val TAG = "TripPlanning"
11
12fun cancelTrip(tripManager: TripManager) {
13    tripManager.cancelTrip(
14        parameters = CancelTripParameters(tripId = null),
15        callback = object : CancelTripCallback {
16            override fun onTripCancelled(response: Result<CancelTripResponse, CancelTripFailure>) {
17                when (response) {
18                    is Result.Success -> {
19                        Log.d(TAG, "Trip cancelled: ${response.value.tripId}")
20                    }
21                    is Result.Failure -> {
22                        Log.e(TAG, "Failed to cancel trip: ${response.failure}")
23                    }
24                }
25            }
26
27            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
28                Log.e(TAG, "Cancel trip unavailable: ${reason.devMessage}")
29            }
30        }
31    )
32}