Routing API Developer's Guide

WaypointParameterType

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, and an optional radius. Parameter structure:

waypoint=[geo!][Type[,StopOverDuration]!]Position[;TransitRadius[;UserLabel[;Heading]]]
Parameter component Structure Description

geo

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 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 cannot be omitted when using user label thus it is empty):
&waypoint0=geo!37.7914050,-122.3987030;;My Home

// 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. Note that 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 (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, i.e. 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=street![Type[,StopOverDuration]!][DisplayPosition[;UserLabel]]!StreetPosition
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.

StreetPosition

Latitude,Longitude[,Altitude][;StreetName]

WGS-84 degrees between -90 and 90. Altitude in meters.

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 can be omitted:
&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

// user label only (display position cannot be omitted when using user label so it is empty):
&waypoint0=geo!;My Home!37.7914055,-122.3987033;ABC Street