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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.NavigableLocation
3
import com.tomtom.automotive.integration.client.api.trip.TripManager
4
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningCallback
5
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningFailure
6
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningParameters
7
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningResponse
8
import com.tomtom.automotive.integration.client.api.model.trip.Trip
9
import com.tomtom.automotive.integration.client.common.Callback
10
import com.tomtom.automotive.integration.client.common.Result
11
import com.tomtom.automotive.integration.client.common.SdkReleasable
12

13
private val TAG = "TripPlanning"
14
private var planTripReleasable: SdkReleasable? = null
15
private var currentTrip: Trip? = null
16

17
fun 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.Coordinate
3
import com.tomtom.automotive.integration.client.api.model.NavigableLocation
4
import com.tomtom.automotive.integration.client.api.trip.TripManager
5
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningCallback
6
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningFailure
7
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningParameters
8
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningResponse
9
import com.tomtom.automotive.integration.client.common.Callback
10
import com.tomtom.automotive.integration.client.common.Result
11
import com.tomtom.automotive.integration.client.common.SdkReleasable
12

13
private val TAG = "TripPlanning"
14
private var planTripReleasable: SdkReleasable? = null
15

16
fun 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
49
val 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.NavigableLocation
3
import com.tomtom.automotive.integration.client.api.model.trip.TripPlanningAvoids
4
import com.tomtom.automotive.integration.client.api.trip.TripManager
5
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningCallback
6
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningFailure
7
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningParameters
8
import com.tomtom.automotive.integration.client.api.trip.plantrip.TripPlanningResponse
9
import com.tomtom.automotive.integration.client.common.Callback
10
import com.tomtom.automotive.integration.client.common.Result
11

12
private val TAG = "TripPlanning"
13

14
fun 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.NavigableLocation
3
import com.tomtom.automotive.integration.client.api.model.trip.RouteStop
4
import com.tomtom.automotive.integration.client.api.trip.TripManager
5
import com.tomtom.automotive.integration.client.api.trip.waypoints.AddWaypointParameters
6
import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsCallback
7
import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsFailure
8
import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsResponse
9
import com.tomtom.automotive.integration.client.common.Callback
10
import com.tomtom.automotive.integration.client.common.Result
11

12
private val TAG = "TripPlanning"
13

14
fun 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.trip.RouteStop
3
import com.tomtom.automotive.integration.client.api.trip.TripManager
4
import com.tomtom.automotive.integration.client.api.trip.waypoints.RemoveWaypointParameters
5
import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsCallback
6
import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsFailure
7
import com.tomtom.automotive.integration.client.api.trip.waypoints.UpdateWaypointsResponse
8
import com.tomtom.automotive.integration.client.common.Callback
9
import com.tomtom.automotive.integration.client.common.Result
10

11
private val TAG = "TripPlanning"
12

13
fun 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.trip.TripManager
3
import com.tomtom.automotive.integration.client.api.trip.tripprogress.TripProgressInfo
4
import com.tomtom.automotive.integration.client.api.trip.tripprogress.TripProgressListener
5
import com.tomtom.automotive.integration.client.api.trip.tripprogress.TripProgressParameters
6
import com.tomtom.automotive.integration.client.common.Callback
7
import com.tomtom.automotive.integration.client.common.SdkReleasable
8

9
private val TAG = "TripPlanning"
10
private var tripProgressReleasable: SdkReleasable? = null
11

12
fun 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

29
fun 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.

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.Coordinate
3
import com.tomtom.automotive.integration.client.api.model.quantity.Distance
4
import com.tomtom.automotive.integration.client.api.trip.TripManager
5
import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineCallback
6
import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineFailure
7
import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineParameters
8
import com.tomtom.automotive.integration.client.api.trip.routepolyline.RoutePolylineResponse
9
import com.tomtom.automotive.integration.client.common.Callback
10
import com.tomtom.automotive.integration.client.common.Result
11
import com.tomtom.automotive.integration.client.common.SdkReleasable
12

13
private val TAG = "TripPlanning"
14
private var routePolylineReleasable: SdkReleasable? = null
15

16
fun 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
52
fun 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.trip.TripManager
3
import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripCallback
4
import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripFailure
5
import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripParameters
6
import com.tomtom.automotive.integration.client.api.trip.canceltrip.CancelTripResponse
7
import com.tomtom.automotive.integration.client.common.Callback
8
import com.tomtom.automotive.integration.client.common.Result
9

10
private val TAG = "TripPlanning"
11

12
fun 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
}