Importing, Exporting and Modifying Routes

VERSION 1.15.0
PUBLIC PREVIEW

In addition to generating routes, the SDK allows developers to manipulate them to a limited degree. 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 kinds 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 be places that 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 show it on a map), it must be turned into a TomTom route. There are two ways to do this:

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

This tutorial contains code snippets to do all of these things 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 from it. Use a third-party GPX file parser library to do so. 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 by using the track points in 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. This is not to be confused with the off-road navigation described in the OffRoadTomTomNavigationFactory page.

Exporting a route into a GPX file

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

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

Every leg of a route is self-contained. This means that a route can be split 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

Routes can be joined 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.

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: