Specify route waypoints in one of the following manners:
- a rough position:
GeoWaypointParameterType - a reference to a street:
NavigationWaypointParameter with StreetPositions - an exact reference to a link:
NavigationWaypointParameter with LinkPositions
GeoWaypointParameterType
The GeoWaypointParameterType defines a waypoint by latitude and longitude coordinates, as well as optional radius, user label and heading, and has the following parameter structure:
waypoint=[geo!][Type[,StopOverDuration]!]Position[;TransitRadius[;UserLabel[;Heading]]]
| Parameter Component | Structure | Description |
| geo | | Indicates that the parameter contains a geographical position. |
| [Type] | Enum[stopOver! | passThrough!] | 180 degree turns are allowed for stopOver but not for passThrough. Waypoints defined through a drag-n-drop action should be marked as pass-through. PassThrough waypoints will not appear in the list of maneuvers. |
| [,StopOverDuration] | common:DurationType
| Stopover delay in seconds. Impacts time-aware calculations. Ignored for passThrough. |
| Position | Latitude, Longitude, [Altitude]; 37.7914050,-122.3987030,25;
| Latitude WGS-84 degrees between -90 and 90. Longitude WGS-84 degrees between -180 and 180. Altitude in meters. |
| [TransitRadius] | TransitRadius 200
| Matching Links are selected within the specified TransitRadius, in meters. For example to drive past a city without necessarily going into the city center you can specify the coordinates of the center and a TransitRadius of 5000m. |
| [UserLabel] | String ;My Home
| Custom label identifying this waypoint. |
| [Heading] | Floating-point value in range [0, 360] | Heading (at the startpoint), in degrees starting at true north and continuing clockwise around the compass. North is 0 degrees, East is 90 degrees, South is 180 degrees, and West is 270 degrees. |
Examples of GeoWaypointParameterType
// using a coordinate without a radius:
&waypoint0=geo!37.7914050,-122.3987030
// using a coordinate:
&waypoint0=geo!37.7914050,-122.3987030
// using a coordinate omitting the "geo!" prefix ("geo" is the default mode):
&waypoint0=37.7914050,-122.3987030
// using a coordinate for a pass-through waypoint:
&waypoint0=passThrough!37.7914050,-122.3987030
// using a coordinate plus transit radius:
&waypoint0=geo!37.7914050,-122.3987030;500
// using a coordinate plus transit radius and user label:
&waypoint0=geo!37.7914050,-122.3987030;500;My Home
// using a coordinate with user label only (transit radius is mandatory and specified as
// empty):
&waypoint0=geo!37.7914050,-122.3987030;;My Home
// using a coordinate with heading South (TransitRadius and UserLabel are mandatory and specified as
// empty):
&waypoint0=geo!37.7914050,-122.3987030;;;180
// specifying stopover delay as 30s
&waypont0=geo!stopOver,30!37.3914050,-122.3987939
NavigationWaypointParameterType with StreetPositions
The NavigationWaypointParameter defines a waypoint by street position and name. The street name helps select the right road in complex intersection scenarios such as a bridge crossing another road or in case of off-road locations near highways. A common use case for this scenario is when the user specifies a waypoint by selecting a place or a location after a search. To avoid the waypoint being matched to a highway in an off-road scenario, it is sufficient to specify an off-road location as a street position without an optional street name. For more details, see the structure of StreetPosition.
The optional display position of the waypoint defines where the location is displayed on a map. It denotes the center of the location and is not navigable, it is not located on a link in the routing network in contrast to the navigation positions of a location. The display position allows the routing engine to decide whether the waypoint is located on the left or on the right-hand side of the route.
The parameter structure is as follows:
waypoint0=street![Type[,StopOverDuration]!][DisplayPosition[;UserLabel[;StreetSideMatchMode]]]!StreetPosition[!Heading[!TransitRadius]]
| URL Component | Structure | Description |
| street | street! | Indicates that parameters contains a street position. |
| [Type] | Enum[stopOver | passThrough] | 180 degree turns are allowed for stopOver but not for passThrough. Waypoints defined through a drag-n-drop action should be marked as pass-through. PassThrough waypoints will not appear in the list of maneuvers. |
| [,StopOverDuration] | common:DurationType
| Stopover delay in seconds. Impacts time-aware calculations. Ignored for passThrough. |
| [DisplayPosition] | Latitude, Longitude, [Altitude] 37.3456,56.778,567
| Latitude WGS-84 degrees between -90 and 90. Longitude WGS-84 degrees between -180 and 180. Altitude in meters. |
| [UserLabel] | ;String ;My Home
| Custom label identifying this waypoint. |
| [StreetSideMatchMode] | Enum[matchAlways | matchOnlyIfDivided] matchOnlyIfDivided
| Intended mode for street side matching of this location. Defaults to matchOnlyIfDivided if omitted. |
| StreetPosition | Latitude,Longitude[,Altitude][;StreetName] | WGS-84 degrees between -90 and 90. Altitude in meters. |
| [Heading] | Floating-point value in range [0, 360] | Heading in degrees starting at true north and continuing clockwise around the compass. North is 0 degrees, East is 90 degrees, South is 180 degrees, and West is 270 degrees. |
| [TransitRadius] | TransitRadius 20
| Matching Links are selected within the specified TransitRadius, in meters. For example to select a link by name without knowing exactly where the link is, you can specify the coordinates of the approximate position and a TransitRadius of 20m. Note that specifying a TransitRadius of more than 100m does not have any effect (as opposed to using TransitRadius in a GeoWaypointParameterType). |
Examples of NavigationWaypointParameterType with StreetPosition
// using street position
&waypoint0=street!37.7914050,-122.3987030!37.7914055,-122.3987033;ABC Street
// using street position with additional stopover delay 45s
&waypoint0=street!stopOver,45!37.7914050,-122.3987030!37.7914055,-122.3987033;ABC Street
// the display position is optional:
&waypoint1=street!!37.7914055,-122.3987033;ABC Street
// using display position plus user label:
&waypoint1=street!37.79156,-122.39825;My Home!37.7914055,-122.3987033;ABC Street
// using display position plus user label and forcing side of street matching:
&waypoint1=street!37.79156,-122.39825;My Home;matchAlways!37.7914055,-122.3987033;ABC Street
// using display position forcing side of street matching (label is mandatory and specified empty):
&location=street!37.79156,-122.39825;;matchAlways!37.7914055,-122.3987033;ABC Street
// user label only (display position is mandatory and specified as
// empty):
&waypoint1=street!;My Home!37.7914055,-122.3987033;ABC Street
// using display position plus user label and forcing side of street matching:
&location=street!37.79156,-122.39825;Favorite place;matchAlways!37.7914055,-122.3987033;ABC Street
// user label only (display position cannot be omitted when using user label so it is empty):
&location=street!;Favorite place!37.7914055,-122.3987033;ABC Street
// force side of street only (display position and user label cannot be omitted so are left empty):
&location=street!;;matchAlways!37.7914055,-122.3987033;ABC Street
// using a transit radius of 20m and heading of 90° to select correct side of a highway:
&waypoint1=street!stopOver!!49.177664,9.902077;A6!90!20
NavigationWaypointParameterType with LinkPositions
The NavigationWaypointParameter defines a waypoint by LinkId and optional Spot value. Spot is defined as the fractional distance from the link's reference-node to the non-reference node, with a value between 0 and 1. When no Spot value nor DisplayPosition is given in request then default value 0.5 is assumed
The optional display position of the waypoint defines where the location is displayed on a map. It denotes the center of the location and is not navigable, it is not located on a link in the routing network in contrast to the navigation positions of a location. The display position allows the routing engine to decide whether the waypoint is located on the left or on the right-hand side of the route.
Parameter structure:
waypoint0=link[!Type[,StopOverDuration]][![DisplayPosition][;UserLabel]]!LinkPosition
| URL component | Structure | Description |
| link | link! | Indicates that request contains a link position. |
| [Type] | Enum[stopOver!| passThrough!] | 180 degree turns are allowed for stopOver but not for passThrough. Waypoints defined through a drag-n-drop action should be marked as pass-through. PassThrough waypoints will not appear in the list of maneuvers. |
| [,StopOverDuration] | common:DurationType
| Stopover delay in seconds. Impacts time-aware calculations. Ignored for passThrough. |
| [DisplayPosition] | Latitude, Longitude, [Altitude] | Latitude WGS-84 degrees between -90 and 90. Longitude WGS-84 degrees between -180 and 180. Altitude in meters. |
| [UserLabel] | ;String | Custom label identifying this waypoint. |
| LinkPosition | LinkId[,Spot] | ID of the link position with mandatory direction prefix (+,-,*) and optional relative position of the location along the link with a value between 0 and 1. When no spot value nor display position is given in the request then default value 0.5 is assumed. |
Examples of NavigationWaypointParameterType with LinkPosition
// using exact link information with display position and spot:
&waypoint0=link!37.7914050,-122.3987030!-743460791,0.8996
// using exact link information with display position and spot and additional stopover delay of 5 minutes:
&waypoint0=link!stopOver,300!37.7914050,-122.3987030!-743460791,0.8996
// the display position is optional:
&waypoint0=link!!-743460795,0.1342
&waypoint0=link!-743460795,0.1342
// using user label:
&waypoint0=link!37.7914050,-122.3987030;My Home!-743460791,0.8996
// using user label without display position:
&waypoint1=link!;My Work!-743460795
// link traveled in any direction:
&waypoint0=link!*743460795
