Importing, exporting, and modifying routes

In addition to generating routes, the SDK allows developers to manipulate them to a limited extent. Specifically, you can:

• Import routes from GPX files.
• Export routes to GPX files.
• Split one route into smaller routes.
• Combine multiple routes into one larger route.

These manipulations are done by treating a route as a series of points. A route in the SDK can contain two types of points:

• Waypoints are locations that a route can be planned to pass through. They generate arrival events when the driver reaches them. For example, these waypoints could represent places a driver wants to visit on a road trip or delivery locations for a cargo van.
• Supporting points are geographical points that define the geometry of an existing route.

Before the SDK can use a series of points as a route (e.g., to display it on a map), it must be turned into a TomTom route. There are two ways to do this:

• Plan a new route that passes through the route’s waypoints.
• Reconstruct the route from its supporting points. This results in a route with geometry similar to the original. The returned RoutePlanningResponse can be used in the SDK like any other route. To include waypoints during route reconstruction, divide the geometry into legs that connect the waypoints, and pass them as a list of RouteLegOptions instances.

This tutorial contains code snippets for all of the above actions, except for planning a new route, which is explained in the Waypoints and custom routes guide.

Constructing a route from a GPX file

To use a route from a GPX file, first extract the route data using a third-party GPX file parser library. This example uses com.github.ticofab:android-gpx-parser:v2.2.0.

1val parser = io.ticofab.androidgpxparser.parser.GPXParser()
2val gpx = parser.parse(gpxInputStream)
3val tracks = gpx.tracks.map { trk ->
4    trk.trackSegments.map { trkseg ->
5        trkseg.trackPoints.map { point ->
6            GeoPoint(point.latitude, point.longitude)
7        }
8    }
9}
10val waypoints = gpx.wayPoints.map { GeoPoint(it.latitude, it.longitude) }

Then, create a route either by reconstructing it using the track points from the imported geometry as supporting points, or by planning a new one that passes through the imported waypoints.

This functionality produces a navigable route matched to the road network. It is not to be confused with the off-road navigation, described on the OffRoadTomTomNavigationFactory page.

Exporting a route into a GPX file

To export a route from the SDK, extract its legs as track segments:

1fun routeToGpx(
2    route: Route,
3    out: Writer,
4) {
5    with(out) {
6        write("<gpx>\n\t<trk>")
7        route.routeStops.forEach { stop ->
8            write(
9                "\n\t\t<wpt lat=\"${stop.navigableCoordinates.first().latitude}\"" +
10                    "lon=\"${stop.navigableCoordinates.first().longitude}\"></wpt>",
11            )
12        }
13        route.legs.forEach { leg ->
14            write("\n\t\t<trkseg>")
15            leg.points.forEach { point ->
16                write("\n\t\t\t<trkpt lat=\"${point.latitude}\" lon=\"${point.longitude}\"></trkpt>")
17            }
18            write("\n\t\t</trkseg>")
19        }
20        write("\n</trk>\n</gpx>")
21    }
22}

Splitting a route

Each leg of a route is self-contained. This means you can split a route into combinations of one or more legs:

1fun splitRoute(
2    route: Route,
3    waypointIndex: Int,
4) {
5    require(route.legs.size > waypointIndex + 1)
6    val firstHalf = route.legs.subList(0, waypointIndex)
7    val secondHalf = route.legs.subList(waypointIndex, route.legs.size)
8
9    val firstGeometry = firstHalf.flatMap { it.points }
10    val secondGeometry = secondHalf.flatMap { it.points }
11}

Once the legs have been split, you can reconstruct them into separate routes.

Combining routes

You can join routes by combining their geometries:

1fun joinRoutes(
2    route1: Route,
3    route2: Route,
4) {
5    val geometry1 = route1.geometry
6    val geometry2 = route2.geometry
7
8    val joinedGeometry = geometry1 + geometry2
9}

The resulting geometrycan then be used to reconstruct the combined route.

Navigating an imported route

The imported route can then be navigated like a regular route. You can find more information on how the deviations are handled here.

Next steps

Since you have learned how to modify a route, here are recommendations for the next steps:

• Planning a route
• Waypoints and custom routes
• Reconstructing a route from a polyline
• Showing routes on the map