Route handle

A route handle encodes a path from a previously calculated route. It can be used to compactly cache a route for a brief amount of time. Thus, it can be used to retrieve more data along the route and get updated traffic information.

However, it does not store the route data itself, meaning that it can not be used to retrieve exactly the same traffic data.

For sample requests of the route handle API, see these tutorials:

• Generate route handle
• Use route handle
• Use route handle with parameter
• Use route handle with forbidden transport mode
• Use invalid route handle

For code samples that demonstrate how to use the origin parameter to get an updated route and route handle, see these tutorials:

• Update origin of a route
• Get route handle for shorter route
• Get route handle for shorter route - part 2
• Specify origin off the route

Validity

A route handle encodes a path tightly coupled to the underlying map data. There are roughly three scenarios that can invalidate an existing handle:

1. The encoding and/or decoding method changes, invalidating all existing handles on a new release. This happens rarely.
2. The topology of the map data changes, invalidating all affected handles. These can be changes in the real world like a highway exit being added or removed, or virtual changes like roads being split into multi-digitized roads. All handles containing changed segments on their path are invalidated. A segment is also considered changed if a road is added/removed at the beginning/end of the segment, even if this road is not used by the route. Topological changes happen rarely, but become more likely with increasing length of the route.
3. When calculating electric vehicle routes, updates or removals of charging stations will invalidate all handles using these charging stations.

Note that regardless of the frequency of these changes invalidating some or all route handles, a user should always be prepared to handle failures. A simple procedure to handle these failures would be to recalculate the route to retrieve a new (valid) route handle.

Parameters

Parameters used to calculate the route are not encoded in the route handle, so they should be specified again when recreating a route using routeHandle.

For example, the transportMode parameter does not have to match the transport mode previously used for route calculation. However, when using a different transport mode, the request may fail, e.g. when the route has road segments forbidden for the provided transport mode.

EV parameters

The route handle endpoint supports all electric vehicle (EV) parameters that are used to calculate the route with the exception of the following:

• makeReachable,
• preferredBrands.