Waypoints Sequence Extension API Developer's Guide

FindPickups

Use the resource findpickups to get a an optimal sequence of optional waypoints.

.../2/findpickups.json?<parameter1>=<value1>&<parameter2>=<value2>&...

Required Parameters

Parameter Type Description
app_id String Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. See Acquiring Credentials.
app_code String Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. See Acquiring Credentials.
capacity Number Amount of payload the vehicle inclunding trailers can carry, volume and/or weight. No unit is specified, but the value must be in the same unit as the waypoint pickup load values.
departure DateTimeString Time when travel is expected to start. Note that traffic speed and incidents are currently not taken into account when calculating the route. departure is required, if trafficmode:enabled is set or if properties are added to waypoints.
The format is as xsd type xs:datetime
[-]CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm]
For Example: 2014-11-11T16:52:00+2b02:00, 2014-11-11T16:52:00Z
destinationN Waypoint with ID; lat,lon; constraints... (see WaypointWithIdType) Intermediate destinations, at least one. If no end parameter is provided, one of these values is selected as end of the sequence. Waypoints of destination parameters can have appointment or access hour constraints.

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.

The waypoint id can be followed by a semicolon separated list of constraints. Supported constraints:

  • before:destination3 (ordering constraint, several comma separated 'before' destinations are allowed per way point). Currently not supported for pickup along route.
  • acc:mo12:00:00+02:00|mo18:00:00+02:00 (access time frame), in combination with st. Currently not supported for pickup along route.
  • at:2016-10-14T16:00:00+02:00 (appointment time = exact time to be there), in combination with st. Currently not supported for pickup along route.
  • st:900 (service time = delay at the way point)
  • pickup:MyPacket;capacity:11 Name and required capacity of an optional load item
  • drop:MyPacket;value:50 Name and gained value/revenue for dropping the picked up item.

Pickup and dropoff: Each id must appear not more often than twice, once for "pickup:" and once for "drop:". "drop:" if ommited the value gets dropped at the final destination ("end"). Each pair of pickup/drop must be associated with a value: field. value can be put together with any of the other fields, but must be set.

If any if these constraints is used, a departure time must be given.

driverCost Number Cost per hour. No currency is specified, but the value must be in the same currency as the vehicleCost and the waypoint drop-off values.
mode String The routing mode specifies how the route is to be calculated. The parameter must be specified on the following pattern:
mode={type};{transport_mode};{traffic_mode}
In this pattern:
  • type: fastest | shortest
  • transport_mode: car | truck | pedestrian
  • traffic_mode: traffic:enabled | traffic:disabled. Note that traffic speed and incidents are currently not taken into account.
The Waypoints Sequence Extension API also supports route feature weightings such as tollRoads, motorways or boatFerrys. Please see the description of the RoutingModeType in HERE Routing API for details. Please note that route weightings are separated by commas, e.g. ...traffic:disabled;tunnel:-2,motorway=-1

The parameter mode is required.

start Waypoint with ID Starting Position of the Journey. For Example: start=52.2,8.1
vehicleCost Number Cost per kilometer. No currency is specified, but the value must be in the same currency as the driverCost and the waypoint drop-off values.

Optional Parameters

Parameter Type Description
avoidLinks List of Link Ids Links that the route may not cross.
avoidArea List of Bounding Boxes Areas which the route must not cross.
end Waypoint with ID Optional Position to be reached at the end of the journey. This value can be omitted. In this case the journey will end at any of the destinations.
hasTrailer Boolean The value indicates if a truck has a trailer.
height Number Defines the height of the truck in meters.
jsonCallback String

Specifies the name of a user-defined function used to wrap the JSON response (JSONP).

If a JSON callback is set, the http response status is always "200 OK". In the case of an error onErrors is set to true and the response field errors contains an error description.

length Number Defines the length of the truck in meter.
limitedWeight Number Defines vehicle weight including trailers and shipped goods, in tons.
maxDetour Number Overall maximum additional seconds spent to pickup and drop-off items along the route, compared to the time without picking up anything.
requestId Text Clients may pass in an arbitrary string to trace request processing through the system. The requestId is mirrored in the response of the service.
restTimes Driving and Rest Specification Type Specification of driving and rest times. This parameter is currently ignored.
shippedHazardousGoods List of Strings List of hazardous goods.

For Example: ..&shippedHazardousGoods=flammable,harmfulToWater&..

trailersCount Number Defines number of trailers.
trailerWeight Number Defines trailer weight including shipped goods, in tons.
truckType String Either truck or tractorTruck. Default is truck.
verbosity String One of low, medium or high. Default is high. Set to medium or high to get the interconnections in the result. Set to high to get the estimated departure or arrival time in the result.
weightPerAxle Number Defines the vehicle's weight per axle in tons.
width Number Defines the width of the truck in meters.

Hazardous Goods

FindSequence requests can include the following hazardous goods:
explosive
Explosive material
gas
Gas
flammable
Flammable material
combustible
Combustible material
organic
Organic material
poison
Poison
radioActive
Radio-active material
corrosive
Corrosive material
poisonousInhalation
Materials that are poisonous upon inhalation
harmfulToWater
Materials that are harmful to water
other
Other types of hazardous materials

Please see HERE Routing API for a comprehensive list of supported values.