Waypoint parameters

Waypoints are used to describe the origins and destinations in a matrix request. They consist of coordinates, but may optionally include other details, which could influence the matrix calculation.

SideOfStreetHint

The sideOfStreetHint parameter specifies the preferred side of street for the waypoint. It is typically the location of a POI (point of interest) on the side of the road. Setting this parameter is useful, for example, when the destinations represent drop-off points for deliveries.

sideOfStreetHint consists of coordinates and an optional parameter, matchSideOfStreet. This setting determines how the hint would be handled. The possible values are always, meaning the hint should always be used, and onlyIfDivided, which means the hint should only be used on roads where traffic in opposite directions is divided; either there's a physical separation between lanes, or it's legally not allowed to cross them. By default, the sideOfStreetHint is only used on divided streets.

Course and minCourseDistance

The course parameter specifies the direction in which the waypoint is left, if it's an origin, or in which it should be reached, if it's a destination. In practice it is a clockwise angle, with values ranging from 0 (north) to 359. Use this parameter, for example, if there's a desired course heading at a destination. The matrix calculation would take that into account, if possible.

When considering origins, the course parameter is often used with another waypoint parameter, minCourseDistance. It is the minimum distance in which the route should continue in the given course. For example, if the matrix calculation is done while driving in a certain direction, then the driver may want to continue in that direction and avoid turns for a while.

nameHint, radius, snapRadius

You can use the nameHint, radius and snapRadius parameters to guide the matrix calculation in finding an origin/destination waypoint.

With a nameHint, the calculation will find the waypoint with the most similar name. A hint can be e.g. north when wanting to use I66 North vs. I66 south.

On the other hand, if the exact location is unknown or is not important, the radius parameter can be used, so that all locations within the radius will be considered for the route calculation. In contrast to the regular radius parameter, snapRadius sorts potential candidates in order of "significance". The snapRadius is most helpful in matching waypoint on Drag and drop interface and not supposed to be used in Matrix Routing. For snapRadius details, see Matching waypoint on drag-and-drop interface use case routing dev guide.

Note

Using these parameters means that the location that is used for the route calculation, may not be the same as the input coordinates.

For example, if each origin in the matrix request represents a waypoint on a route, but different entries use different underlying locations, then the connecting parts between those entries would be missing.

The example demonstrates how to go from A to B and then C. This requires a matrix request with origins A and B, and destinations B and C. If you set B's radius to 200 meters, the calculation might use B1 and B2 as underlying locations. This means that the actual length of the route from A to B and then C is longer than the one returned in the matrix result.