Developer

Importing, Exporting and Modifying Routes

VERSION 1.20.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.

Next steps

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