Estimated Time of Arrival (ETA) is the time when a vehicle is expected to arrive at a certain place. The Routing API service offers the possibility to calculate the ETA based on an initially calculated route and the current position of the vehicle.
Workflow
As a first step the route the vehicle will probably take has to be calculated using calculateRoute or calculateRoutePost. Request in the parameter results the ROUTE_ID to obtain in the response the routeId in order to calculate the ETA with every new vehicle position. This initially calculated route must contain all relevant opening intervals for the waypoints and the drivers' working hours preset, if applicable. Use all other parameters as usual, e.g., the traffic mode, routing options and so on.
Now, with every new vehicle position the ETA can be calculated with getEstimatedTimeOfArrival using the above routeId. If the vehicle is somewhere on the route, its geographical position has to be specified along with the name of the waypoint which is the next on the route. If the vehicle is at a waypoint, only the waypoint name has to be specified. It is assumed that the position is the vehicle's current position and was captured recently. If that is not the case the time when the vehicle was at the given position can be specified using the parameter time. For best results the ETA will be calculated with traffic mode REALISTIC taking into account live traffic, so time should only be within several minutes in the past or in the future, otherwise live traffic cannot be considered properly.
The result of such an ETA calculation is the list of all remaining waypoints. Among other things each of the remaining waypoints contains the estimated time of arrival consisting of date and time as well as the remaining distance and travel time.
Usually, the routeId of the initially calculated route will be used for each ETA request, but if the vehicle has probably left the route or if the arrival at the destination is delayed for some reason, a new route will be calculated to obtain a more realistic ETA and a new routeId will be returned.
See Waypoints for information on using the routeId after a map update has been updated.
Position
The vehicle is currently on the route to a waypoint. The next waypoint to be reached has to be specified. A heading and heading tolerance can be given to determine the driving direction and to detect if the vehicle is still on the correct route.
If the given position is too far away from the route, it is assumed that the vehicle has left the route. A new route will be calculated from that position in order to calculate the most realistic ETA.
Some on-board units also provide information on the driving direction, the heading of the vehicle. If specified, it will be used to determine if the vehicle has left the route. In such cases, a new route may be calculated selecting a different road close to the given position which matches the heading.
The heading tolerance determines how to interpret the heading. Only roads for which the difference between the direction and the heading are within this tolerance are taken into account for the current position.
Waypoint
The vehicle is currently at a waypoint of the route. Already performed service time can be specified to be considered in the ETA calculation.
When opening intervals are specified for the waypoint in question and the vehicle arrives
- before an opening interval, there will be a waiting or a rest time scheduled until the waypoint opens,
- within an opening interval, service will be performed, it is not relevant whether or not the remaining service time will be finished before the waypoint closes,
- after the last opening interval, there will be an OPENING_INTERVAL violation.
Drivers' Working Hours
ETA calculation also supports drivers' working hours. The preset to be respected has to be specified in the calculation of the initial route and will be maintained for every subsequent ETA request. For each of these ETA requests the work logbook has to be specified in order to schedule breaks and rests properly.
It may happen, depending on the current position of the vehicle on the route and the current traffic situation, that one or more of the remaining waypoints will be reached so that the maximum driving or travel time allowed by the preset are exceeded. The corresponding violations will be reported with each of the remaining waypoints for which such a rule is violated.
Which restrictions apply
- All off-road and on-road waypoints in the routing request must be assigned a unique name to obtain the route id. Otherwise, the route id cannot be used for ETA calculation because the waypoints cannot be identified.
- Route-manipulation waypoints and combined transport waypoints are not supported for ETA calculation.
- The query parameters waypoint and position are mutually exclusive.
- ETA cannot be calculated for positions before the first waypoint, but it is possible to calculate ETA if the vehicle position is anywhere on the route after the first waypoint.
- If the vehicle position cannot be matched to any road, an error will be returned.
- If the performed service time specified for a position at a waypoint is greater than the service time initially planned, service will be assumed to be completed.
Try it in the ETA Showcase.