Route handle

A route handle encodes a path from previously calculated route, but not the route data itself (e.g., there is no way to retrieve exactly the same traffic data). A route can be decoded from a handle as long as the service uses the same map data used during encoding.

All parameters of the /routes endpoint are supported, except for origin, destination, via, alternatives and routingMode.

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.

Current limitations

Route handles are not working with the ev[makeReachable] parameter.

Basic usage

To generate routeHandle, it should be explicitly requested by specifying return=routeHandle in route calculation request.

To reproduce a route with previously generated routeHandle, the handle should be sent to the /v8/routes/ endpoint, together with any other desired parameters.

Since routeHandle is not a permanent identifier it can change with the map version.

Example request to generate routeHandle:

curl -X GET \
    'https://router.hereapi.com/v8/routes?origin=52.511985,13.240523&transportMode=car&destination=52.500541,13.363060&return=routeHandle'
{
  "routes": [
    {
      "id": "10afccf7-2ae2-4204-87af-0b6b1f80f9b2",
      "sections": [
        {
          "id": "0020bb1b-89f1-412f-b2cd-0fbb17e90799",
          "type": "vehicle",
          "departure": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.51199,
                "lng": 13.240519
              },
              "originalLocation": {
                "lat": 52.511986,
                "lng": 13.240523
              }
            }
          },
          "arrival": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.50044,
                "lng": 13.363361
              },
              "originalLocation": {
                "lat": 52.50054,
                "lng": 13.36306
              }
            }
          },
          "transport": {
            "mode": "car"
          }
        }
      ],
      "routeHandle": "{routeHandle}"
    }
  ]
}

And example request to re-use the routeHandle:

curl -X GET \
    'https://router.hereapi.com/v8/routes/{routeHandle}?transportMode=car'
{
  "routes": [
    {
      "id": "3e496eeb-d44e-409a-90d5-bd1d384fbbef",
      "sections": [
        {
          "id": "fb02810a-8b37-4f5a-9630-631d64178395",
          "type": "vehicle",
          "departure": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.51199,
                "lng": 13.240519
              },
              "originalLocation": {
                "lat": 52.511986,
                "lng": 13.240523
              }
            }
          },
          "arrival": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.50044,
                "lng": 13.363361
              },
              "originalLocation": {
                "lat": 52.50054,
                "lng": 13.36306
              }
            }
          },
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

Other parameters could be used with the same routeHandle, for example:

curl -X GET \
    'https://router.hereapi.com/v8/routes/{routeHandle}?transportMode=truck&avoid=tollRoad,difficultTurns&return=polyline'
{
  "routes": [
    {
      "id": "0701e5f3-7647-4b0f-84f2-fde255191f24",
      "sections": [
        {
          "id": "278505db-d04d-49a7-8cd4-f52be24c3804",
          "type": "vehicle",
          "departure": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.51199,
                "lng": 13.240519
              },
              "originalLocation": {
                "lat": 52.511986,
                "lng": 13.240523
              }
            }
          },
          "arrival": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.50044,
                "lng": 13.363361
              },
              "originalLocation": {
                "lat": 52.50054,
                "lng": 13.36306
              }
            }
          },
          "polyline": "BGqvilkDuskoZhDtH_JvCnL4DjNgF_EwC_EwCrO0FvHkDvMgFvoCsdjzC4hBvb0KrO0KkD4wB8BwgBoV0jLwCokB8B8foBoa0F49CoG0_CoLomF8BsdwCsiB8BsYoBkc8BoVU4NoBoVoBoV8BsiBwCsgCUoL4DsxBkDkwB8GguD0Fs-CsJw9EU4NUwMoBoQU0FoBoV8BgjBT8fnBgKnBsJ7B8L7BsJjD0K3D0KjD0KvC0KvCoV7BsTA4SwCsO4DgKgF8GoG0F8L0FkDsJ8B4I8BwM8BoVU0UwCkwBkDkrBoGg_CsE8iCwCs2BkDouB8BgeoBkXoBwWUkNkDwW4D03BU4N8B0eoB0UU8LoBsToBwRoB4NUkIUsOkD0tBkD41BkI8-DsJs1E8B4mB4NslHwCsd4D4_BoBsToBgUwH0uDA4DkDgtBoBkSUwHwC4hBU0KoGw8CkD8uB8BwbsE41BkDozBsE4kC8B4XgF0wCwCkhB4IgnEgFgrCsE8iC4Dk_BgF0wCgFgwCoGgpDoB8V0F4iD_EwCzFsE3DwH3DwHjDsJvCoLT8L3S4XnLgPjSsY_YgjBjmB03BrxBslC_O8V_J8QvHoQjNkc_OkhBvM8azPsiBjNkc3cghCzZ41BrO0e7GoL_E4I3D4IvCoG3DsJvM4c_EwM3N0evM8anGsOrJ8VvC4I7B4InBkI7BsOvC0evCoa7B8VvCwb3D0oBnBwMnBwRT8LAkIUgPUkI8B4NkD4SwCgPoB8LoB0KoB8LUsJUkNA0FTsJnB4NTsEnB4I7B4ITgFjDwMzF8VjD8L_E8V3D8QnGwbzFkXjDwMjDkNzF8VnL8uB7Lw0B_E4XrEgZzKs2BnBoG7B4IvC0K3DoQ3DsO_EsT_E4SjD0KnGsY3DsOrE4S7BgKnGkczK0tB7GkczFkX3D0PrEoQ_E8Q3I8fzFoV3DkSjDoQvCsTnQkkCnB0FjDoL7B4IrJgoB7GsdzFkX3D0PrE8QrEkS7BoGjD8L3I0evRo9B_J8kBrE0P7pB0xEgK0FsEkD4S8QkLiK",
          "transport": {
            "mode": "truck"
          }
        }
      ]
    }
  ]
}

Additional use-cases

Route Handle could be used to retrieve up-to-date travel times on a route calculated earlier:

curl -X GET \
    'https://router.hereapi.com/v8/routes?origin=52.442061,13.283770&transportMode=car&destination=52.558965,13.493431&return=routeHandle,travelSummary'
{
  "routes": [
    {
      "id": "efc8970f-a312-425b-9a37-1cf599c95507",
      "sections": [
        {
          "id": "17cb0d57-9560-4b61-86eb-a221e95c63a9",
          "type": "vehicle",
          "departure": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.44208,
                "lng": 13.283753
              },
              "originalLocation": {
                "lat": 52.442062,
                "lng": 13.28377
              }
            }
          },
          "arrival": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.559002,
                "lng": 13.493394
              },
              "originalLocation": {
                "lat": 52.558964,
                "lng": 13.493431
              }
            }
          },
          "travelSummary": {
            "duration": 3274,
            "length": 23363,
            "baseDuration": 2440
          },
          "transport": {
            "mode": "car"
          }
        }
      ],
      "routeHandle": "{routeHandle}"
    }
  ]
}

And to get a new travel time we could use route handle:

curl -X GET \
    'https://router.hereapi.com/v8/routes/{routeHandle}?transportMode=car&return=travelSummary'
{
  "routes": [
    {
      "id": "fc4d017a-e1bc-47c8-8129-08d63396fe80",
      "sections": [
        {
          "id": "5027a773-0e23-4334-bfbe-338baca8b366",
          "type": "vehicle",
          "departure": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.44208,
                "lng": 13.283753
              },
              "originalLocation": {
                "lat": 52.442062,
                "lng": 13.28377
              }
            }
          },
          "arrival": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.559002,
                "lng": 13.493394
              },
              "originalLocation": {
                "lat": 52.558964,
                "lng": 13.493431
              }
            }
          },
          "travelSummary": {
            "duration": 3297,
            "length": 23363,
            "baseDuration": 2440
          },
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

results matching ""

    No results matching ""