Waypoints Sequence Extension API Developer's Guide

FindSequence Response

This chapter describes the response structure of the HERE Waypoints Sequence Extension API.

Response of the resource findsequence.json

Parameter Type Description
errors List of strings This field provides descriptions of errors which occurred during the calculation. The value is always included in the answer, but is a empty array, if there is no error. errors is providing information if the HTTP response code indicates an error
processingTimeDesc String Calculation time for the result, including the time unit. If the response does not contains an error, the processing time value is included.
requestId String Identifier defined in the request and passed through the system. This field is null, if no such value was defined in the request.
responseCode String This value is set to the HTTP response code. If the parameter jsonCallback is set in the request, the HTTP response code is always 200. In this case this field gives the actual response code.
results List of results This List contains 1 or 0 elements with an ordered list of waypoints. This value is set, if a result is found.
warnings List of OutOfSequence Waypoints This List contains 0 or more elements with an ordered list of waypoints. This value is set only, if no sequence is found due to constraints.

List of Results details

Parameter Type Description
description String Description how the sequence of waypoints was calculated.
distance Number Length of the journey defined by the sequence of waypoints.

Unit: Meters

interconnections List of times and distances For each interconnections between two subsequent waypoints the time and distance are given. The values for an interconnection include the costs for route between two waypoints. The interconnection starts with the departure at a waypoint and ends when the service at the next waypoint begins. This includes possible waiting times at the second waypoint but does not include the service time there. In particular a possible rest during the service time is not booked to an interconnection. Each list entry consists of
  • fromWaypoint:

    Origin waypoint id of the interconnection. The field refers to the id in the waypoints list.

  • toWaypoint:

    destination waypoint id of the interconnection. The field value refers to the id in the waypoints list.

  • time:

    The driving time between the given waypoints. This is the actual driving time and does not cover resting or waiting.

    Unit: Seconds

  • distance:

    The travel distance between the given waypoints.

    Unit: Meters

  • rest:

    The time spent for resting on the way.

    Unit: Seconds

  • waiting:

    The time spent waiting until the service can start at the waypoint.

    Unit: Seconds

time Number Time needed for the journey, defined by the sequence of waypoints, depending on the provided parameters this value includes traffic or a static time calculation.

Unit: Seconds

timeBreakdown Object with Numbers Detailed information about how the time needed for the journey in spent:
  • driving
  • service
  • rest
  • waiting

Unit: Seconds

waypoints List of ordered waypoints
The found sequence of waypoints. For each waypoint
  • id
  • lat
  • lng
  • sequence
  • estimatedArrival
  • estimatedDeparture
  • fulfilledConstraints
are given.

The id value is taken from the request. If you sent the request without id, one is generated. Latitude (lat) and Longitude (lng) are WGS-84 degree coordinates. id, lat, lng and sequence are always part of a waypoint entry. The field sequence contains the order of the waypoints in the calculated sequence.

If you choose to make a calculation including traffic information or if you set constraints, the field estimatedDeparture contains the projected departure at the waypoint. If you choose to set constraints, the field estimatedArrival contains the projected arrival at the waypoint. Otherwise estimatedDeparture and estimatedArrival are null.

If a constraint is set for a waypoint, these field contains a list with the fulfilled constraints in the input format.

Details of Warnings

The field warnings contains issues preventing the successful calculation of a sequence. The only field inside is outOfSequenceWaypoints which contains a list of waypoints that cannot be reached because of constraints. An entry of outOfSequenceWaypoints is described in this table.

Parameter Type Description
id String Description how the sequence of waypoints was calculated.
lat Number The latitude of the waypoint.
lng Number The longitude of the waypoint.
failedConstraints List

List containing pairs of unmet constraints and reasons.

  • constraint
  • reason

The constraint reflects the input setting in the same format. The reason defines why the constraint was not met: 0:Undetermined, 1:not reachable in time, 2:service time did not fit, 3: conflicts with arrival time of final waypoint