Developer

Waypoints and custom routes

VERSION 1.26.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 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 entire route but must be passed through during 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 additional leg in the response. Each added waypoint also results in an extra RouteStop in the routeStops list, where the first element is the origin and the last element is the destination.

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 when calculating travel time and traffic delays.
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: