Search for content

Route IDs

Route IDs

A route can be represented by a route ID which can be used in subsequent requests to refer to that route and is valid for 12 hours.

Such a route ID can be requested 

  • when calculating a route using calculateRoute or calculateRoutePost,
  • when calculating alternative routes using the result ALTERNATIVE_ROUTES with calculateRoute or calculateRoutePost - each alternative route is then represented by a route ID,
  • for relations of a distance matrix using getRouteId in the Matrix Routing API
  • for matched tracks when using the result ROUTE_ID with getMatchedTrack in the Map Matching API.

 

In a subsequent request it can be used to

  1. fetch results of the routes using getRouteByRouteId, in particular for matrix relations
  2. recalculate route results with different parameters using calculateRoute or calculateRoutePost,
  3. calculate route results such as toll or emissions using calculateRoute or calculateRoutePost, in particular for a matched track
  4. calculate the ETA using getEstimatedTimeOfArrival,
  5. calculate reachable areas around the route using calculateReachableAreas or startAndCreateReachableAreas,
    calculate reachable locations along the route using startAndCreateReachableLocations.

For a route represented by a route ID the route path will never change, i.e. when using the route ID in a subsequent request the result will never be a different route path.

1. Fetch route results

By default, getRouteByRouteId returns the results of the initial route calculation use the same parameters. But with the results parameter other results can be requested. These results are then based on the same route path and the same parameters.

This is useful when requesting route results incrementally, just requesting results this way is much faster than recalculating the route. It is also useful when requesting route results for matrix relations as the Matrix Routing API does not support other results than the key values of the route. For example, in order to display the polyline of matrix relations on a map, first request the routeId from the Matrix Routing API and then retrieve the POLYLINE result from the Routing API.

The path of the route will not change nor the distance or the polyline, but other results may be slightly different as some data may have changed, in particular live traffic but also exchange rates, custom road attributes or even map data when being updated.

Limitations

  • The result ROUTE_ID will be ignored, as the response will always contain the requested route ID.
  • The result ALTERNATIVE_ROUTES is not allowed, at all, as this operation does not perform any route calculation. Use calculateRoute or calculateRoutePost instead to calculate alternative routes with a route ID.
  • Results available in the POST operation only such as those regarding drivers' working hours and electric vehicle are available only for route IDs which were calculated using calculateRoutePost.
  • Results regarding emissions are not available for route IDs which were calculated using calculateRoute or calculateRoutePost and using the parameter emissionOptions. Emission-related results and emissionOptions are mutually exclusive.

 

2. Recalculate the route with different parameters

A route ID can be used instead of the waypoint list in a subsequent request to calculate a route. The path of the route will not change nor the distance or the polyline, only results such as the travel time, toll, emissions or events may change according to the specified parameters.

This feature can be used to find out the travel time for the same route at a different date and time. When using options[trafficMode]=REALISTIC the travel time may change with every request. The route may even become violated when a road on the route is blocked for the specified vehicle at that date and time.

To find out the toll prices for the same route with a different vehicle, specify the vehicle parameters or the vehicle profile accordingly. The route may become violated when a road on the route is blocked for the specified vehicle, e.g. a weight or a height violation including those provided by custom road attribute scenarios. When changing the profile the route calculation may even fail, e.g. when calculating a truck route for a bicycle using highways.

All parameters which control the path of the route by preferring or avoiding certain roads such as options[allowedCountries], options[prohibitedCountries], options[avoid], options[preferTurnsOnPassengerSide], options[blockIntersectingRoads] and options[routingMode] will be ignored, and a warning will be issued.

3. Calculate route results such as toll or emissions

For a route ID returned for a matched track in the Map Matching API it might be necessary to calculate results such as toll or emissions for validation or billing reasons. As the Map Matching API does not know about the exact vehicle, the resulting route ID can be used in a calculate route request specifying all the required parameters to calculate the desired results. See Recalculate Toll and Emissions for details.

4. Calculate the estimated time of arrival

The route ID can be used to refer to a route path when calculating the estimated time of arrival. See Estimated Time of Arrival for details.

5. Calculate reachable areas or locations

The route ID can be used to refer to a route path when calculating the reachable areas around or locations along the route. See Reachable Areas and Locations for details.

Map Updates

The route represented by a route ID will automatically be updated when being used for the first time after the map has been updated. A new map may mean in some cases that the route will be different from the initial one, for example, when roads used by the route have changed or were deleted in the new map. The request which updates the route will issue a warning ROUTING_UPDATED_ROUTE_ID in order to notify that the route was updated.

Limitations

  • Route IDs from other services than the Routing API (e.g. Matrix Routing API, Map Matching API) cannot be used with getEstimatedTimeOfArrival.
  • Route IDs from other services than the Routing API will not be updated automatically when the map is updated, it becomes invalid an cannot be used, anymore. In such a case recalculate the route ID.
  • Route IDs from the Map Matching API cannot be used with getRouteByRouteId. This is because the matched track has no reference to some vehicle.

Try it in the RouteIds code sample.