Developer

Waypoints and custom routes

VERSION 1.20.0
PUBLIC PREVIEW

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.

Waypoints

Waypoints are specific points through which a route should be calculated. They do not define the whole route, but are passed through in the journey from origin to destination.

The maximum allowed number of waypoints is 150.

Waypoints are defined using a list of ItineraryPoint. By default, they are included in the route in the order they are specified. In routing planning each waypoint results in an extra leg in the response. Also, each added waypoint results in an extra RouteStop in the routeStops list in the response, containing the route’s origin as a first list element and destination as a last.

1val amsterdam = ItineraryPoint(Place(GeoPoint(52.377956, 4.897070)))
2val rotterdam = ItineraryPoint(Place(GeoPoint(51.926517, 4.462456)))
3val hague = ItineraryPoint(Place(GeoPoint(52.078663, 4.288788)))
4val utrecht = ItineraryPoint(Place(GeoPoint(52.091458, 5.11518)))
5val itinerary = Itinerary(
6    origin = amsterdam,
7    destination = rotterdam,
8    waypoints = listOf(hague, utrecht),
9)
10val routePlanningOptions = RoutePlanningOptions(itinerary = itinerary)

Custom routes

The supportingPoints parameter is used to reconstruct a route from an imported polyline:

  • The sequence of supporting points provided 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 minDeviationDistance and 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 traffic incidents of the type ROAD_CLOSURE, which are ignored for the travel time and traffic delay calculations.
1val supportingPoints = loadSupportingPointsFromFile()
2val amsterdam = GeoPoint(52.377956, 4.897070)
3val rotterdam = GeoPoint(51.926517, 4.462456)
4val routePlanningOptions = RoutePlanningOptions(
5    itinerary = Itinerary(origin = amsterdam, destination = rotterdam),
6    routeLegOptions = supportingPoints.map { RouteLegOptions(supportingPoints = it) },
7)

Next steps

Since you have learned how to work with waypoints and supporting points, here are recommendations for the next steps: