Send a Request

A route calculation consists of a single GET request. The only required parameters are an origin and a destination, given by two pairs of WGS84 coordinates in the form <latitude>,<longitude>; and a transportation mode, which can currently be any of car, truck, or pedestrian. The following request will calculate a car route with default options:

curl -X GET \
    'https://router.hereapi.com/v8/routes?transportMode=car&origin=52.5308,13.3847&destination=52.5264,13.3686&return=summary'

Note

Depending on your authentication method you either need to add an Authorization header with a Bearer token or a query parameter to the example requests shown here. See Authentication for details.

Note

Postman users can import these examples: Import > Paste Raw Text

If the route calculation was successful, the response contains the calculated route with departure and arrival times in one or more sections. Additional summary information such as length and duration is also provided.

{
  "routes": [
    {
      "id": "cc0441f1-b8ca-4410-95d5-bfd930053c03",
      "sections": [
        {
          "id": "256fef6e-6712-47fe-8e68-095c1204eb1a",
          "type": "vehicle",
          "departure": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5309837,
                "lng": 13.384567
              },
              "originalLocation": {
                "lat": 52.5307999,
                "lng": 13.3847
              }
            }
          },
          "arrival": {
            "place": {
              "type": "place",
              "location": {
                "lat": 52.5263761,
                "lng": 13.3686186
              },
              "originalLocation": {
                "lat": 52.5263999,
                "lng": 13.3686
              }
            }
          },
          "summary": {
            "duration": 243,
            "length": 1206,
            "baseDuration": 136
          },
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

No Routes Possible

Some requests will not result in any routes for a number of reasons. This example requests a route from the HERE Berlin office to the HERE Chicago office:

curl -X GET \
  'https://router.hereapi.com/v8/routes?transportMode=car&origin=52.5308,13.3847&destination=41.8845,-87.6386' \

Of course, the Atlantic Ocean is between these two offices. This causes the route calculation to fail with the following response:

{
  "notice": [
    {
      "title": "Route calculation failed: Couldn't find a route.",
      "code": "routeCalculationFailed"
    }
  ],
  "routes": []
}

Encoding your request

Some parameter values, especially waypoint specifications, use a structured string in their values. Content characters may then clash with control characters in your request. Consider for example a request like

https://router.hereapi.com/v8/routes?transportMode=car&origin=54.32556,14.65314&destination=54.65422,14.66636;nameHint=Fish & Chips! St. 25

Such a request is ambiguous due to the use of control characters (&, !) in the value of nameHint. Such characters need to be appropriately percent-encoded for disambiguation. The following guidelines apply for percent-encoding your requests:

  • Never percent encode & or = when they are used as control characters.
  • If your request does not use control characters as content (i.e., they are only used for their intended control meaning), you don't need to encode anything.
  • If your request does use control characters for content, percent-encode them, but leave the controlling characters unencoded. Do not double-encode. In such mixed requests, all naked control characters will be interpreted as control, and all encoded ones as content.

Accordingly, the above request should be encoded as

https://router.hereapi.com/v8/routes?transportMode=car&origin=53.32556,14.65314&destination=53.65422,14.66636;nameHint=Fish%20%26%20Chips%21%20St.%2025

results matching ""

    No results matching ""