Key concepts

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

Waypoints

The HERE Waypoints Sequence API v8 uses waypoints to identify the stops in your journey. The 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 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. You can also add a "human-readable" label to your waypoints. For an example, see Car with Traffic Information Waypoint Sequence.

Limits and Impact on Pricing

The maximum number of waypoints including the start point and end point is 202. Billing is based on consumed transactions. For each request a transaction count is calculated, depending on the number of waypoints, clustering and whether traffic is enabled. For actual numbers and other contractual models see HERE Base Plan Pricing, in particular the sections "Transaction definitions and excluded use cases" and "HERE Location Service Rates". If the routing mode pedestrian is used, the distance between each two of the waypoints must not be greater than 5km.

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. See HERE Routing API for a comprehensive description of the routing mode including possible limitations on some subfields. However, the parameter mode may 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. Please see the transport mode description in HERE Routing API. There is also information on the available status, e.g. if a transport mode is provided with "beta" limitations.

• 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 does not 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. There is detailed information coming with the description of the RoutingModeType in HERE Routing API. Please note that routing features are separated by commas, if there is more than one: ...traffic:disabled;tunnel:-2,motorway:-1.

For examples, see Examples.

Findpickups versus findsequence

For findsequence, all waypoints are mandatory, none of them can be skipped. For findpickups, only the start and the end waypoints are mandatory, while each of the intermediate waypoints is optional and can be skipped. It is 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 will echo this value in the response, be it success or failure. While you can use any string as the request identifier, we recommend using a UUID to uniquely identify your requests.