Basic Route Handle Usage

A route handle can be generated by explicitly requesting return=routeHandle in a route calculation request.

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

Example request to generate routeHandle:

curl -X GET \
    'https://router.hereapi.com/v8/routes?origin=52.550028,13.302349&destination=52.553272,13.305195&return=routeHandle&transportMode=car'
{
  "routes": [
    {
      "id": "84cfeded-3a5c-4cc2-8b74-1dce40f36710",
      "sections": [
        {
          "id": "999da998-db00-4876-80e2-24718393db74",
          "type": "vehicle",
          "departure": {
            "time": "2021-06-29T11:39:30+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5500411,
                "lng": 13.3023036
              },
              "originalLocation": {
                "lat": 52.5500279,
                "lng": 13.302349
              }
            }
          },
          "arrival": {
            "time": "2021-06-29T11:40:21+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5532843,
                "lng": 13.3051593
              },
              "originalLocation": {
                "lat": 52.553272,
                "lng": 13.305195
              }
            }
          },
          "transport": {
            "mode": "car"
          }
        }
      ],
      "routeHandle": "{routeHandle}"
    }
  ]
}

And example request to use the routeHandle:

curl -X GET \
    'https://router.hereapi.com/v8/routes/{routeHandle}?transportMode=car'
{
  "routes": [
    {
      "id": "31f954d6-b6e5-47eb-ab31-5ebbe8d0a850",
      "sections": [
        {
          "id": "a00b4f5e-bc7e-433e-87a2-473414f91d3d",
          "type": "vehicle",
          "departure": {
            "time": "2021-06-29T11:42:13+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5500411,
                "lng": 13.3023036
              },
              "originalLocation": {
                "lat": 52.5500279,
                "lng": 13.302349
              }
            }
          },
          "arrival": {
            "time": "2021-06-29T11:42:49+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5532843,
                "lng": 13.3051593
              },
              "originalLocation": {
                "lat": 52.553272,
                "lng": 13.305195
              }
            }
          },
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

And an example with different different parameters, e.g. avoid[features]=controlledAccessHighway, that yields a critical notice:

curl -X GET \
    'https://router.hereapi.com/v8/routes/{routeHandle}?transportMode=car&avoid[features]=controlledAccessHighway'
{
  "routes": [
    {
      "id": "e7784661-dd6f-4da9-b610-9c45e8d95d15",
      "sections": [
        {
          "id": "b5d0423f-d7df-4b43-b86b-656e0735a0c3",
          "type": "vehicle",
          "departure": {
            "time": "2021-06-29T11:45:08+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5500411,
                "lng": 13.3023036
              },
              "originalLocation": {
                "lat": 52.5500279,
                "lng": 13.302349
              }
            }
          },
          "arrival": {
            "time": "2021-06-29T11:45:32+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5532843,
                "lng": 13.3051593
              },
              "originalLocation": {
                "lat": 52.553272,
                "lng": 13.305195
              }
            }
          },
          "notices": [
            {
              "title": "Violated avoid controlled-access highway.",
              "code": "violatedAvoidControlledAccessHighway",
              "severity": "critical"
            }
          ],
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

And another example with a transport mode that is not allowed on the path encoded by the route handle:

curl -X GET \
    'https://router.hereapi.com/v8/routes/{routeHandle}?transportMode=pedestrian'
{
  "notices": [
    {
      "title": "Route handle decoding failed due to forbidden segments for the specified transport mode.",
      "code": "violatedTransportModeInRouteHandleDecoding",
      "severity": "critical"
    }
  ],
  "routes": []
}

Finally, an example with an invalid route handle that can not be decoded:

curl -X GET \
    'https://router.hereapi.com/v8/routes/InvalidRouteHandle?transportMode=car'
{
  "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"
}

results matching ""

    No results matching ""