Key concepts - HERE Waypoints Sequence API v8

This section provides information essential to understanding and using the HERE Waypoints Sequence API v8.

Waypoints

HERE Waypoints Sequence API v8 uses waypoints to identify the stops in your journey.

Waypoints are defined at a minimum by WGS-84 compliant latitude and longitude pairs with values between -90 and 90, and -180 and 180 respectively.

Each journey must have a start and an end (optional, the service assumes the last waypoint is the final destination if you do not define one) point, which you can define explicitly with the relevant parameters (start and end in the resource findsequence).

All other waypoints are identified with the parameters destination1, destination2, and so on for however many waypoints you wish to sequence.

The maximum number of waypoints, including the start and end points, is 202.

In the pedestrian transport mode, the distance between waypoints can't be greater than 5 km.

Pricing

For information about the pricing of HERE Waypoints Sequence API v8 requests, see the HERE Base Plan page. If you have questions about pricing, contact us.

Routing modes

When you use HERE Waypoints Sequence API v8 to optimize a series of waypoints, you need to specify the routing mode in your request. For more information about routing modes including possible limitations on some subfields, see HERE Routing API v8 Developer Guide.

The mode parameter can include three to four subfields as follows:

• routing type

  The options available are as follows:

  • fastest: routing favors the least amount of travel time, can consider traffic if enabled. This is the most commonly used routing type.
  • shortest: routing favors the least amount of travel distance and disregards traffic.

• transport mode

  The transport mode allows you to specify the type of vehicle. Supported options are car, truck, pedestrian, bicycle, scooter,taxi or bus. The modes for taxi and bus work best with traffic set to enabled, because it takes advantage of bus and taxi lanes on and near high-traffic roads. To learn more, see HERE Routing API v8 Developer Guide.

• traffic enabled

  Enabling traffic allows HERE Waypoints Sequence API v8 to consider up-to-date traffic information when calculating a route. Additionally, this live traffic information is augmented with historical traffic speeds when considering travel times in the future. The calculation for the current time uses live traffic information. For longer routes, the live traffic information is mixed with historical traffic information for the later portions of the route. Routes calculated for future times use historical traffic information to determine traffic speeds, as well as considering any long-term road closures on the route. If the request doesn't include a departure time, then all current live traffic events (at the time of calculation) are assumed to be valid for the entire length of the route.

• routing features

  The routing features can be used to define special conditions on calculated routes. Routing features include weighting roads such as toll road, motorways, etc. Routing features are separated by commas, if there is more than one: ...traffic:disabled;tunnel:-2,motorway:-1. To learn more, see HERE Routing API v8 Developer Guide.

findpickups and findsequence parameters

For findsequence, all waypoints are mandatory and none of them can be skipped. For findpickups, only the start and the end waypoints are mandatory. Every intermediate waypoint is optional and can be skipped. It's currently not possible, to compute the optimal route given a mixture of these waypoint types (some mandatory, some optional). However, a mixed scenario can be approximated by assigning very high values to the intermediate waypoints to ensure they'll become part of the route.

Request tracing

When submitting a bug report or asking for support, always provide the routing request URI, request identifiers, and the corresponding error code, if any.

X-Request-ID

You can tag your requests with a request identifier using the non-standard HTTP header X-Request-ID. The service echoes this value in the response, be it success or failure. While you can use any string as the request identifier, it's recommended to use a universally unique identifier (UUID).