Waypoint

A waypoint specifies a point that the requested route needs to traverse. Both origin and destination are themselves waypoints, but a request may specify many more intermediate waypoints with via as well. See Route Via Intermediate Waypoint for examples.

Waypoints may represent stopover points (that is, points where some time will be spent before retaking the route), or passthrough points that only influence the route's shape, but where no actual stop is carried out.

In addition to a WGS84 coordinate, a waypoint incorporates several other options and details, related to either the physical location point or to the stop itself.

Some examples of options include the stopover time (as described above), and navigational hints such as requiring the route to arrive on a specified duration, or to ignore maneuvers (e.g., turns) at the start of the route for a specified distance.

For related sample requests, see these tutorials:

• Route to correct side of street
• Specify arrival direction at destination
• Route with course heading and distance at start

Route via intermediate waypoint

To add a stopover in your route, specify it using the via parameter in your request.

You can specify a list of via waypoints to divide the resulting route into sections:

1. from the origin to the first via
2. to any subsequent via, for every point in the requested order
3. and from the last via until the destination

Set a passThrough option for each via parameter. In case you set passThrough to true, then, at the waypoint when calculating the route, the router will behave as follows:

• does not introduce a stopover
• does not split the route into sections
• avoids changing the direction of travel

Additionally, specify return=passthrough to get information about passthrough via waypoints in the response. This includes the location to which the passthrough via was matched and an offset into the polyline if the polyline was requested as well.

There is currently no limit on the number of via waypoints, but there is a limit on the size of the HTTP request. Depending on the textual length of the options, like via waypoints, or avoid options requested, the numbers of via waypoints that can be specified will be different. For this reason, specifying more than 100 waypoints is not recommended.

To realize a route matching use case and re-create routes with coordinates coming from a GPS trace or an existing route, you need a high number of waypoints. It is recommended to use the route import service for this scenario, as it supports a much larger number of points in the input.

For a simple tutorial of how to add one stopover waypoint to a route calculation, see Add stopover.

For sample requests that demonstrate waypoint calculation, see these tutorials:

• Route with multiple via waypoints
• Calculate route with a passthrough waypoint
• Calculate route with course heading and distance at start
• Specify arrival direction at destination

Matching waypoints

There are two waypoint matching strategies for a waypoint.

• radius parameter: This will match the waypoint to all segments in the area, letting the router choose the one that is optimal for the route.

• snapRadius parameter. In this case, the waypoint will be matched to the closest most-significant road in the given radius.

These parameters are mutually exclusive. For example, you can use radius with the first waypoint and snapRadius with the second one, But you can't set them both for a single waypoint.

• Matching waypoint on drag-and-drop interface