Waypoints and custom routes

VERSION 0.45.0

The user may wish to customize their route by designating specific points that the route must pass through. This can be accomplished in one of two ways:

By specifying waypoints as part of the Itinerary in route planning requests. Waypoints are interim stops or places that the user wishes to visit during their journey.
By planning a custom route that follows a polyline. A polyline is a sequence of coordinate pairs that defines the desired route path. While the planned route will follow the shape of the polyline as closely as possible, it is not guaranteed that each point on the polyline will be visited in case of road network differences. This feature allows the users to import tracks from external sources or to recreate paths they have driven before.

Setup

When creating an instance of OnlineTomTomNavigationFactory.Configuration, use the StandaloneRouteProgressEngine value for the RouteProgressEngine parameter.

1let configuration = OnlineTomTomNavigationFactory.Configuration(
2    locationProvider: locationProvider,
3    routeReplanner: routeReplanner,
4    apiKey: "YOUR_API_KEY",
5    routeProgressEngine: StandaloneRouteProgressEngine()
6)
7
8let navigation = try OnlineTomTomNavigationFactory.create(configuration: configuration)

Waypoints

The maximum allowed number of waypoints is 150.

When creating RoutePlanningOptions, there are two ways to specify waypoints:

By using only their coordinates.
By providing detailed data in addtion to the coordinates, such as address and name.

To define a waypoint using only its coordinates, use the ItineraryPoint initializer that accepts a coordinate pair:

1let amsterdamCoordinate = CLLocationCoordinate2DMake(52.3764527, 4.9062047)
2let berlinCoordinate = CLLocationCoordinate2DMake(52.5069751, 13.3631919)
3let hagueCoordinate = CLLocationCoordinate2DMake(52.078663, 4.288788)
4let itinerary = Itinerary(
5    origin: ItineraryPoint(coordinate: amsterdamCoordinate),
6    destination: ItineraryPoint(coordinate: berlinCoordinate),
7    waypoints: [ItineraryPoint(coordinate: hagueCoordinate)]
8)
9
10let options: RoutePlanningOptions
11do {
12    options = try RoutePlanningOptions(itinerary: itinerary)
13} catch {
14    print("Invalid planning options: \(error.localizedDescription)")
15    return
16}

To define a waypoint using its coordinates, address, and name, use the ItineraryPoint initializer that accepts a Place object:

1let amsterdamCoordinate = CLLocationCoordinate2DMake(52.3764527, 4.9062047)
2let berlinCoordinate = CLLocationCoordinate2DMake(52.5069751, 13.3631919)
3let hagueCoordinate = CLLocationCoordinate2DMake(52.078663, 4.288788)
4let hagueAddress = Address(
5    streetNumber: "70",
6    streetName: "De Perponcherstraat",
7    municipality: "Den Haag",
8    postalCode: "2518 SW",
9    country: "The Netherlands"
10)
11let haguePlace = Place(coordinate: hagueCoordinate, name: "Den Haag", address: hagueAddress)
12
13let itinerary = Itinerary(
14    origin: ItineraryPoint(coordinate: amsterdamCoordinate),
15    destination: ItineraryPoint(coordinate: berlinCoordinate),
16    waypoints: [ItineraryPoint(place: haguePlace)]
17)
18
19let options: RoutePlanningOptions
20do {
21    options = try RoutePlanningOptions(itinerary: itinerary)
22} catch {
23    print("Invalid planning options: \(error.localizedDescription)")
24    return
25}

A succesful route planning returns a Route array. Waypoints are included in the Route in the order they are specified in the Itinerary of the RoutePlanningOptions. When planning a route, each waypoint results in an extra leg in the response.

The Route.routeStops property contains an array of RouteStop instances to describe the resulting itinerary. Waypoints from this array can also be accessed using the Route.waypoints property.

Custom routes

The user may want to import a custom polyline and reconstruct a route based on it. The RouteLegOptions.supportingPoints parameter is used for this:

The provided sequence of supporting points is used as input for route reconstruction.
The RoutePlanningOptions.routeLegOptions accepts the supporting points per leg.
- The number of items in the RoutePlanningOptions.routeLegOptions array must match the number of legs of the route as specified by the Itinerary.
Alternative routes are calculated using the origin point, potential waypoints, and destination point as specified by the Itinerary.
If both AlternativeRoutesOptions.minDeviationDistance and AlternativeRoutesOptions.minDeviationTime are set to zero, the origin and destination points are expected to be at (or very near) the beginning and end of the reference route.
The reference route may contain road closures, which are ignored for the calculation of travel time and traffic delay for the reference route.

1let amsterdamCoordinate = CLLocationCoordinate2DMake(52.3764527, 4.9062047)
2let berlinCoordinate = CLLocationCoordinate2DMake(52.5069751, 13.3631919)
3let supportingPoints = loadSupportingPointsFromFile()
4let routeLegOptions = supportingPoints.map { RouteLegOptions(supportingPoints: $0) }
5let itinerary = Itinerary(
6    origin: ItineraryPoint(coordinate: amsterdamCoordinate),
7    destination: ItineraryPoint(coordinate: berlinCoordinate)
8)
9
10let options: RoutePlanningOptions
11do {
12    options = try RoutePlanningOptions(
13        itinerary: itinerary,
14        alternativeRoutesOptions: AlternativeRoutesOptions(
15            maxAlternatives: 1,
16            minDeviationDistance: Measurement.tt.meters(100),
17            minDeviationTime: Measurement.tt.seconds(10)
18        ),
19        routeLegOptions: routeLegOptions
20    )
21} catch {
22    print("Invalid planning options: \(error.localizedDescription)")
23    return
24}

Next steps

Since you have learned how to add waypoints, here are recommendations for the next steps: