A waypoint specifies a point that the requested route needs to traverse. Both
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:
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:
- from the
origin to the first
- to any subsequent
via, for every point in the requested order
- and from the last
via until the
passThrough option for each
via parameter. In case you set
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
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:
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.