How to use route handles

To generate a route handle, you need to specify 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'

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

The handle stores the path the routes takes but doesn't store any parameters you sent in the request, for example transportMode, or departureTime.

Use route handle

To reproduce a route with a previously generated routeHandle, you need to send the handle to the /v8/routes/ endpoint, together with any other needed parameters:

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

You don't have to send the same parameters that were used in the original requests. See this tutorial for examples.

Route handle invalidation

A routeHandle can be invalidated due to map data changes along the route or changes to the service, prompting the service to responds with this 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"
}

You need to be prepared to handle this scenario, usually by recomputing the original route.

Route handle limitations

Due to limitations in the route handle format a route handle with more than 250 sections isn't supported.