Waypoints and custom routes
Planning a route may involve locations beyond the origin and destination. These can be used in two different ways:
- Adding Waypoints to a route. These can be stops along the way, or places that the user wants to pass by during the journey.
- Constructing a custom route from a polyline (defined as a list of supporting points). This allows users to import routes from another source or reconstruct driven paths.
In a more advanced navigation experience, the user may want to provide more locations through which the route should be calculated. These optional intermediate locations are known as waypoints.
The maximum allowed number of waypoints is 150.
Waypoints are defined using an array of
ItineraryPoints, which is stored in the
waypoints property of the
Itinerary type. The
Itinerary type is stored in the
itinerary property of
ItineraryPoint includes: - an
id property, used to synchronize between the waypoints in the input to planning (
RoutingOptions) and those in the output (
Route). - a
place property of the type
Place, which includes the place’s coordinates (
CLLocationCoordinate2D), plus its name and address if they are supplied.
There are two options for defining waypoints while creating
RoutingOptions: with just its coordinates or with detailed data as well.
To define a waypoint using only its coordinates:
1let amsterdamCoordinate = CLLocationCoordinate2DMake(52.3764527, 4.9062047)2let berlinCoordinate = CLLocationCoordinate2DMake(52.5069751, 13.3631919)3let hagueCoordinate = CLLocationCoordinate2DMake(52.078663, 4.288788)45let options = RoutingOptionsBuilder(origin: amsterdamCoordinate, destination: berlinCoordinate)6 .with(waypointCoordinate: hagueCoordinate)7 .build()
To define a waypoint using its coordinates, address, and name:
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)1213let options = RoutingOptionsBuilder(origin: amsterdamCoordinate, destination: berlinCoordinate)14 .with(waypoint: ItineraryPoint(place: haguePlace))15 .build()
RoutingOptionsBuilder has several ways to add waypoints to
RoutingOptions. You can choose the one that best fits your purposes. There are two methods for adding waypoints with only coordinates:
public func with(waypointCoordinate: CLLocationCoordinate2D) → Self
public func with(waypointCoordinates: [CLLocationCoordinate2D]) → Self
There are also two methods for adding waypoints with the full
public func with(waypoint: ItineraryPoint) → Self
public func with(waypoints: [ItineraryPoint]) → Self
Route planning returns a
Route array. Waypoints are included in the
Route in the order they are specified in
RoutingOptions. When planning a route, each waypoint results in an extra leg in the response.
Route also contains
routePoints, which is array of
RoutePoint. This array includes values of types
Waypoint (for respective points of route). Waypoints from this array can be accessed via the
waypoints property of
The user may want to import a custom polyline and reconstruct a route based on it. The
supportingPoints parameter is used for this:
- The provided sequence of supporting points is used as input for route reconstruction.
- Alternative routes are calculated between the origin and destination points specified in the base path parameter locations.
- If both
minDeviationTimeare set to zero, the origin and destination points are expected to be at (or very near) the beginning and end of the reference route.
- Waypoints are not supported when using the
- The reference route may contain traffic incidents, 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()45let options = RoutingOptionsBuilder(origin: amsterdamCoordinate, destination: berlinCoordinate)6 .with(supportingPoints: supportingPoints)7 .with(minDeviationDistance: 100)8 .with(minDeviationTime: 10)9 .build()