Optimizing waypoints

The HERE Waypoints Sequence API v8 resource findsequence allows you to optimize for distance covered in a journey or for travel time. Use the parameter improvefor (available values: distance and time). By default, HERE Waypoints Sequence optimizes waypoints for travel time.

HERE Waypoints Sequence API v8 does not include route details in its responses. To request a route, use the HERE Routing API.

Requests to the Routing API must include the route travel mode and two consecutive waypoint coordinates from the response from HERE Waypoints Sequence API v8. If the route includes traffic information, departure time is also required. The response from HERE Waypoints Sequence API v8 provides this information in the element estimatedDeparture.

Time window constraints define opening hours or deadlines for product delivery points or appointments specific to each waypoint. Successful responses contain an optimized waypoint sequence that observes all the time constraints specified in the request in the parameter destinationN. Where this is not possible, the service generates a response without a way point sequence, but hints at conflicting or problematic constraints or waypoints. You must then resubmit the request with relaxed or modified constraints or waypoints. For an example, see Time Constraints Waypoint Sequence.

Sequence constraints between pairs of waypoints define a partial order which is strictly obeyed. Add ;before:destination13 to the waypoints in the request parameters to define sequence constraints. Several 'before's are allowed per way point.

Service time is specific to each waypoint and defines the amount of time to be spent at the waypoint. In other words, it indicates the length of time between arrival at the waypoint and departure from it, for example, to complete the delivery of goods. Service times are taken into account in the optimized waypoint sequence. For an example with rest times at waypoints, see Traffic Info and Rest Time Constraints Waypoint Sequence.

HERE Waypoints Sequence API v8 may take several minutes to calculate a response depending on the parameters specified. Specifically, this calculation time depends on the following:

• the routing mode
• the number of waypoints
• the distances between the individual waypoints

The Routing Mode and its Impact on the Calculation Time

The Routing Mode specifies how the itineraries between the individual waypoints are calculated. This can but does not have to change the resulting sequence of the waypoints. Sequences are more likely to change, if the ratio of travel time or distance between pairs of waypoints changes.

There are multiple parts in the Routing Mode divided by semicolons:

• Type: fastest or shortest, states the preference of fast or short routes between individual waypoints.
• Transport type: whether car, truck or pedestrian mode is used (mode=car;… or mode=truck;...)
• Traffic mode: can be enabled or disabled (mode=...;traffic:enabled).
• Routing features: Using these features, selected types of roads can be avoided during routing by the feature with a negative weight, e.g. mode=...;traffic:enabled;tollroad:-2;tunnel:-1. Roads with avoided features are not necessarily completely excluded from routes. The features are:
  • tollroad
  • motorway
  • boatFerry
  • railFerry
  • tunnel
  • dirtRoad

The mode settings impact the calculation time:

• mode=...;traffic:disabled can be calculated much faster then mode=...;traffic:enabled.
• fastest can be calculated faster than shortest.
• In general car can be calculated faster than truck.
• Configuring a feature to be avoided may result in elevated calculation times.

Enabling traffic reduces the number of accepted waypoints for a request. For actual limits, see the Waypoints Sequence API Reference.

Examples of the Routing Mode are mode=fastest;truck;traffic:disabled or mode=fastest;car;traffic:enabled;tollroad:-2;dirtRoad:-1.

The timeout after which the network connection is closed is set to 300 seconds on the HERE Waypoints Sequence API v8 systems.

Grouping or Clustering nearby Waypoints

Fleet Telematics Waypoints Sequence can be directed to allocate clusters of waypoints to improve quality and performance. There are different types of clustering available:

• by driving distance
• along topology segments (road stretches)
• of time windows at waypoints

Each of the types of clusters follows a different purpose and supports different subsets of the functions of Waypoints Sequence. Support of traffic information is generally not available. The creation of clusters is controlled by the parameter clustering=....

Driving Distance

Waypoints are added to a cluster if each of the waypoints is within a given driving (or walking) distance of each other in both directions. The distance refers to the way following the road network. It is not the air-line distance. This means the matching of the provided coordinate to the road network defines the relevant location, in particular:

• Destinations on a rear building still can be grouped together with destinations on the front building, if matched to the same road.
• Destinations matched on opposite sides of multi-digitized roads are not likely to be grouped.

By default a distance is chosen balancing the quality of the result and the performance of the calculation, but you can overwrite the size of the cluster by adding a distance in meter to the parameter.

This functionality is activated by the parameter clustering=drivingDistance. The optional distance in meters can be provided clustering=drivingDistance:500.

Supported features are:

• optional end point
• departure time
• service time (as part of the destination parameter.

Topology Segments

Topology segments can be understood as a linear stretch of road between two junctions. If this type of clustering is applied, waypoints are added to the same cluster, if they are map-matched to the same topology segment.

This functionality is activated by the parameter clustering=topologySegment.

Supported features are:

• optional end point

Time Windows

Time windows can be set if all waypoints, except for those marking start and end, come with a constraint for access hours, e.g. destination3=ZecheZollverein;51.486665,7.045181;acc:mo12:00:00+02:00|mo13:00:00+02:00;st:900. Only one interval is allowed in the constraints. Destinations are added to the same cluster, if the access hours provided by acc: are identical. The service time at the destination does not impact the selection of the cluster.

This functionality is activated by the parameter clustering=timeWindow.

Supported features are:

• optional end point
• departure time
• service time (as part of the destination parameter).

Default Setting

Impact of constraints on Grouping