What is a route handle

A route handle encodes a previously calculated route. You can use it to cache a route for a limited period of time, retrieve additional data along the route, or get updated traffic information.

Route handles don't store route data, which means that you can't use them to retrieve the same traffic data as the original route calculation.

📘

Note

A route handle is not suitable for persistent route storage. It can be invalidated at any time.

Generate a route handle

To generate a route handle, include return=routeHandle in a route calculation request:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.550028,13.302349&'\
'destination=52.553272,13.305195&'\
'return=routeHandle&'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY'

The response includes a routeHandle field at the route level:

{
  "routes": [
    {
      "id": "84cfeded-3a5c-4cc2-8b74-1dce40f36710",
      "sections": [
        {
          ...
        }
      ],
      "routeHandle": "{ROUTE_HANDLE}"
    }
  ]
}

The handle encodes the path the route takes. It does not store any request parameters, such as transportMode or departureTime.

Use a route handle

To reproduce a route from a previously generated handle, send it to the /v8/routes/{routeHandle} endpoint along with any other required parameters:

curl -gX GET 'https://router.hereapi.com/v8/routes/{ROUTE_HANDLE}?'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY'

You don't have to use the same parameters as in the original request. See Re-evaluate route with different options for examples.

Supported parameters

The /routes/{routeHandle} endpoint supports all parameters of the /routes endpoint, except for the following:

• destination
• via
• alternatives
• routingMode

You can provide the origin parameter to update the starting point of the previously calculated route. For more details, see Update the current route and Adjust the current route after a deviation.

The transportMode parameter doesn't have to match the transport mode used in the original request. However, using a different transport mode may cause the request to fail if the route contains road segments that are forbidden for that transport mode.

EV parameters

Route handles support all electric vehicle (EV) parameters used to calculate the original route, except for the following:

• makeReachable
• preferredBrands
• preferredChargePointOperators
• excludeChargePointOperators
• excludeChargingStations

Validity

Route handles are tightly connected to the underlying map data. The following changes can invalidate route handles:

1. Encoding change: The encoding or decoding method changes, invalidating all existing handles. This happens rarely.
2. Map topology change: The topology of the map data changes, invalidating all affected handles. Examples include a highway exit being added or removed, or roads being split into multi-digitized roads. All handles that contain changed segments are invalidated. A segment is also considered changed if a road is added or removed at its beginning or end, even if that road is not part of the route. Topological changes happen rarely, but become more likely as route length increases.
3. Charging station update (EV routes): Updates to or removals of charging stations invalidate all handles that use those stations.

Handle invalidation errors

A route handle can also be invalidated due to changes in the service. When this happens, the service returns the following error:

{
  "title": "Invalid request",
  "status": 400,
  "code": "E605201",
  "cause": "RouteHandle not valid (anymore). (Re-)calculate route to retrieve new handle.",
  "action": "",
  "correlationId": "bf58bdea-ae23-49f5-8323-ad3a05fafb33"
}

If you get this error, recalculate the original route to obtain a new route handle.

Limitations

Route handles support routes with up to 250 sections.