A location defining a via waypoint.

A via waypoint is a location between origin and destination. The route will do a stop at the via waypoint.

Multiple waypoints can also be specified using multiple via parameters like via=...&via=..., in which case the route will traverse these waypoints sequentially in the order specified in the request.

Format

Format: Place[WaypointOptions]

• Place: {lat},{lng}[PlaceOptions]
• PlaceOptions: ;option1=value1;option2=value2...
• WaypointOptions: !option1=value1!option2=value2...

A waypoint consists of:

• Exactly one place
• Optional settings for the place
• Optional settings for the waypoint itself

Supported place options:

• course: int, degrees clock-wise from north. Indicating desired direction at the place. E.g. 90 indicating east. Often combined with radius and/or minCourseDistance
• sideOfStreetHint: {lat},{lng}. Indicating the side of the street that should be used. E.g. if the location is to the left of the street, the router will prefer using that side in case the street has dividers. E.g. 52.511496,13.304140;sideOfStreetHint=52.512149,13.304076 indicates that the north side of the street should be preferred. This option is required, if matchSideOfStreet is set to always.
• matchSideOfStreet: enum [always, onlyIfDivided]. Specifies how the location set by sideOfStreetHint should be handled. Requires sideOfStreetHint to be specified as well.
  • always : Always prefer the given side of street.
  • onlyIfDivided: Only prefer using side of street set by sideOfStreetHint in case the street has dividers. This is the default behavior.
• nameHint: string. Causes the router to look for the place with the most similar name. This can e.g. include things like: North being used to differentiate between interstates I66 North and I66 South, Downtown Avenue being used to correctly select a residental street.
• radius: int, meters. Asks the router to consider all places within the given radius as potential candidates for route calculation. This can be either because it is not important which place is used, or because it is unknown. Radius more than 200meter are not supported.
• minCourseDistance: int, meters. Asks the routing service to try find a route that avoids actions for the indicated distance. E.g. if the origin is determined by a moving vehicle, the user might not have time to react to early actions.

Supported waypoint options:

• stopDuration: desired duration for the stop, in seconds.

• passThrough: boolean. Asks the router to avoid the following during route calculation:

  • Introducing a stop at the waypoint.
  • Splitting the route into sections.
  • Changing the direction of travel.

  Following scenarios are not supported for passThrough parameter:

  • Setting both stopDuration to a value greater than 0 and passThrough=true.
  • Setting passThrough=true for origin or destination of a route. The default value is false.

Notes:

• Non-structural reserved characters in options' values need to be properly percent-encoded. Please refer to the developers' guide for more details.

Avoid routes that violate certain features of road network or that go through user-specified geographical bounding boxes.

Note that if the origin, destination, or any via is in an avoided area or on an avoided feature, a route is produced that violates the avoid restriction. In such a case, the route is trying to minimize the violation of the avoid restrictions and can therefore include large deviations from a route that is calculated without these avoid restrictions.

It is also possible that the produced route violates the avoid restriction in between waypoints, if no other route is possible or too hard to find. One such example is requesting a route to an island that is only reachable with ferries while specifying avoid[features]=ferry.

Further, avoid can cause the route calculation to fail, if no route is possible or too hard to find.

Specify properties using array notation like avoid[features]=controlledAccessHighway,tunnel.

Defines properties which will be strictly excluded from route calculation.

Defines which attributes are included in the response as part of data representation of a Route or Section.

• polyline - Polyline for the route in Flexible Polyline Encoding. Either a 2D polyline (without elevation specified), or a 3D polyline with the 3rd dimension type Elevation (with elevation specified).
• actions - Actions (such as maneuvers or tasks) that must be taken to complete the section.
• instructions - Include instructions in returned actions. Instructions are localized to the requested language.
• summary - Include summary for the section.
• travelSummary - Include summary for the travel portion of the section.
• turnByTurnActions - Include all information necessary to support turn by turn guidance to complete the section.
• mlDuration - Use a region-specific machine learning model to calculate route duration. Disclaimer: This parameter is currently in beta release, and is therefore subject to breaking changes.
• elevation - Include elevation information in coordinate and geometry types. See e.g. polyline or location.
• routeHandle - Encode calculated route and return a handle which can be used with routes/{routeHandle} to decode the route at a later point in time.
• passthrough - Include information on passthrough via waypoints in the section.
• incidents - Include a list of all incidents applicable to each section. Incidents are localized to the requested language. This requires incidents to be specified as part of the return parameter.
• routingZones - Include information about routing zones each section goes through.

Following restrictions apply when specifying return parameter:

• If actions is requested, then polyline must also be requested as well.
• If instructions is requested, then actions must also be requested as well.
• If turnByTurnActions is requested, then polyline must also be requested as well.
• If at least one attribute is requested within the spans parameter, then polyline must be request as well

Defines which attributes are included in the response spans. For example, attributes,length will enable the fields attributes and length in the route response.

This parameter also requires that the polyline option is set within the return parameter.

Truck specific parameters.

• shippedHazardousGoods: Comma-separated list of shipped hazardous goods in the vehicle. Possible values are:
  • explosive: Explosive material
  • gas: Gas
  • flammable: Flammable material
  • combustible: Combustible material
  • organic: Organic material
  • poison: Poison
  • radioactive: Radioactive material
  • corrosive: Corrosive material
  • poisonousInhalation: Materials that are poisonous upon inhalation
  • harmfulToWater: Materials that are harmful to water
  • other: Other types of hazardous materials
• grossWeight: Vehicle weight including trailers and shipped goods, in kilograms.
• weightPerAxle: Vehicle weight per axle, in kilograms.
• height: Vehicle height, in centimeters.
• width: Vehicle width, in centimeters.
• length: Vehicle length, in centimeters.
• tunnelCategory: Specifies the tunnel category used to restrict transport of specific goods. Possible values:
  • B
  • C
  • D
  • E
• axleCount: Defines total number of axles in the vehicle.
• type: Specifies the type of truck
  • straight: a truck on a single frame with a permanently attached cargo area
  • tractor: a towing vehicle that can pull one or more semi-trailers (aka semi-truck)
• trailerCount: Number of trailers attached to the vehicle.

Disclaimer: This parameter is currently in beta release, and is therefore subject to breaking changes.

EV parameters to be used for calculating consumption and for calculating EV routes with automatically added charging stations.

The following attributes are required for calculating consumption:

• freeFlowSpeedTable
• ascent
• descent

The following attributes are additionally required in order to calculate reachable routes:

• initialCharge
• maxCharge
• connectorTypes
• chargingCurve
• maxChargeAfterChargingStation
• makeReachable set to true

All remaining attributes are optional.

Disclaimer: these parameters are work in progress and functionality is not complete

Additional generic details about the vehicle for which the route is calculated.

Currently, hovOccupancy and speedCap are defined, with limited functionality

Scooter specific parameters.

• allowHighway: Specifies whether scooter is allowed on highway or not. This parameter is optional. If not provided, then by default scooter is not allowed to use highway. There is a similar parameter avoid[features]=controlledAccessHighway to disallow highway usage. avoid[features] takes precedence so if this parameter is also used then scooters are not allowed to use highways even if allowHighway is used with value as true. Possible values:
  • true: scooter is allowed to use highway.
  • false: scooter is not allowed to use highway.

Traffic specific parameters.