Avoidance

Routes can be calculated to avoid specific map features and/or areas.

Map features can be specified by providing a feature category. For example, a route that avoids toll roads can be calculated by specifying avoid[features]=tollRoad when requesting a route. A route that avoids environmental zones can be calculated by specifying avoid[zoneCategories]=environmental.

Specific features of the map can also be avoided by providing an identifier of the feature to be avoided. For example, a route that avoids a specific segment, a part of Invalidenstrasse in Berlin, can be calculated by specifying avoid[segments]=here:cm:segment:207551710. A route that avoids one specific environmental zone ("Berlin Umweltzone") can be calculated by specifying avoid[zoneIdentifiers]=here:cm:envzone:2.

To avoid a whole area, a user specified bounding box can be provided. For example, a route that avoids the Berlin area can be calculated by providing avoid[areas]=bbox:13.082,52.416,13.628,52.626.

Sometimes no route is possible that avoids the feature, for example specifying avoid[features]=ferry to an otherwise inaccessible island. In this case, a route can be returned that makes minimal use of the feature. However, there is no guarantee that a route is returned, if it is only possible by violating avoid.

If a route is returned that violates the avoid request a notice is included to indicate that the route does not avoid the feature.

Example that avoids the specified avoid option

This request successfully avoids the tollRoad feature using the avoid option:

curl -X GET \
  'https://router.hereapi.com/v8/routes?destination=47.168076,11.861380&origin=47.257410,11.351458&transportMode=car&avoid[features]=tollRoad&apikey={YOUR_API_KEY}'

{
  "routes": [
    {
      "id": "428d7f71-f92b-484f-a4b5-d491b35f6210",
      "sections": [
        {
          "arrival": {
            "place": {
              "location": {
                "lat": 47.168049830943349,
                "lng": 11.861283313483
              },
              "type": "place"
            },
            "time": "2019-12-09T16:06:36+01:00"
          },
          "departure": {
            "place": {
              "location": {
                "lat": 47.25743193179369,
                "lng": 11.35145296342671
              },
              "type": "place"
            },
            "time": "2019-12-09T14:23:59+01:00"
          },
          "id": "ccba0c50-76f7-4d55-a8da-ce5c3ee629a9",
          "transport": {
            "mode": "car"
          },
          "type": "vehicle"
        }
      ]
    }
  ]
}

Example that violates the specified avoid option

This request violates the avoid option:

curl -X GET \
  'https://router.hereapi.com/v8/routes?destination=53.863531,14.284817&origin=53.859552,14.271760&transportMode=car&avoid[features]=ferry&apikey={YOUR_API_KEY}'

The response specifies a notice with the code violatedAvoidFerry:

{
  "routes": [
    {
      "id": "7616d85b-da9a-46bd-9b9f-e8dafe34213a",
      "sections": [
        {
          "arrival": {
            "place": {
              "location": {
                "lat": 53.86060992255807,
                "lng": 14.277769988402725
              },
              "type": "place"
            },
            "time": "2019-12-09T14:31:28+01:00"
          },
          "departure": {
            "place": {
              "location": {
                "lat": 53.859547432512048,
                "lng": 14.271750692278147
              },
              "type": "place"
            },
            "time": "2019-12-09T14:08:34+01:00"
          },
          "id": "217649dd-5584-4162-b235-f625f5b25185",
          "transport": {
            "mode": "car"
          },
          "type": "vehicle"
        },
        {
          "arrival": {
            "place": {
              "location": {
                "lat": 53.862169962376359,
                "lng": 14.28596992045641
              },
              "type": "place"
            },
            "time": "2019-12-09T14:42:28+01:00"
          },
          "departure": {
            "place": {
              "location": {
                "lat": 53.86060992255807,
                "lng": 14.277769988402725
              },
              "type": "place"
            },
            "time": "2019-12-09T14:31:28+01:00"
          },
          "id": "e955e9cf-7783-4c77-a9ee-8ba1b409b612",
          "notices": [
            {
              "code": "violatedAvoidFerry",
              "title": "Violated avoid ferry"
            }
          ],
          "transport": {
            "mode": "ferry"
          },
          "type": "vehicle"
        },
        {
          "arrival": {
            "place": {
              "location": {
                "lat": 53.86353185400367,
                "lng": 14.284817911684513
              },
              "type": "place"
            },
            "time": "2019-12-09T14:44:22+01:00"
          },
          "departure": {
            "place": {
              "location": {
                "lat": 53.862169962376359,
                "lng": 14.28596992045641
              },
              "type": "place"
            },
            "time": "2019-12-09T14:42:28+01:00"
          },
          "id": "3a8fe2c0-269a-45f1-a5bb-aab060d78c7c",
          "transport": {
            "mode": "car"
          },
          "type": "vehicle"
        }
      ]
    }
  ]
}

Example that fails with avoid options

This request fails with the avoid option:

curl -X GET 'https://router.hereapi.com/v8/routes?origin=52.531106,13.384915&transportMode=car&destination=55.954408,-3.194735&avoid[features]=ferry,carShuttleTrain&return=summary&apikey={YOUR_API_KEY}'

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

Get detailed section notices

This request specifies waypoints and parameters for a route that does not exist. The result of the calculation is a response that specifies notices for certain sections of the route.

curl -X GET \
  'https://router.hereapi.com/v8/routes?origin=50.892387,20.655124&destination=50.894911,20.64899&transportMode=truck&vehicle[grossWeight]=4000&departureTime=2020-10-28T00:01:00+01:00&apikey={YOUR_API_KEY}'

{
  "routes": [
    {
      "id": "4ff6518f-ebf4-4c69-aa6f-ed1a67c0daec",
      "sections": [
        {
          "id": "f9fd7dca-e7ca-4c95-9033-fb5b395a5452",
          "type": "vehicle",
          "departure": {
            "time": "2020-10-28T00:01:00+01:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 50.8924,
                "lng": 20.655124
              },
              "originalLocation": {
                "lat": 50.892387,
                "lng": 20.6551239
              }
            }
          },
          "arrival": {
            "time": "2020-10-28T00:04:32+01:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 50.8948931,
                "lng": 20.6489882
              },
              "originalLocation": {
                "lat": 50.8949109,
                "lng": 20.64899
              }
            }
          },
          "notices": [
            {
              "title": "Violated vehicle restriction.",
              "code": "violatedVehicleRestriction",
              "severity": "critical",
              "details": [
                {
                  "type": "restriction",
                  "cause": "Route violates vehicle restriction",
                  "maxGrossWeight": 3500,
                  "timeDependent": true
                }
              ]
            }
          ],
          "transport": {
            "mode": "truck"
          }
        }
      ]
    }
  ]
}

Routing zones

Information on routing zones and how to avoid them can be found here.

Avoid areas

For information on how to avoid areas, see here.