Waypoints Sequence Extension API Developer's Guide

Key Concepts

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

Waypoints

The Waypoints Sequence Extension API uses waypoints to identify the stops in your journey. There 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.

The maximum number of waypoints including the start point and end point is 120 without traffic and 50 with traffic. 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 ask the Waypoints Sequence Extension API to optimize a series of waypoints, you need to specify the routing mode in your request. Please see HERE Routing API for a comprehensive desciption 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 for the Waypoints Sequence Extension API are: car, truck or pedestrian.

  • traffic enabled

    Enabling traffic allows the Waypoints Sequence Extension API 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 tollroad, 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 manadatory, 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.