How to avoid areas in routes

The avoid[areas] parameter enables the user to calculate routes that avoid the specified areas.

One or more areas can be specified for avoidance, separated by the | delimiter: avoid[areas]={area1}[|{area2}[|{area3}...]]

Each avoid area can be further qualified with one or more exception areas. Exception areas are excluded from the associated avoidance area: avoid[areas]={area}!exception={area1}[!exception={area2}]...

The following area types are supported. These area types can be used either as the area to avoid, or as an exception:

• bbox - A bounding box defined by two longitudes and two latitudes.
• polygon - A polygon defined as a list of coordinates, or as a Flexible Polyline encoded string.
• corridor - A polyline with a specified radius in meters that defines an area. The polyline can be defined as a list of coordinates, or as a Flexible Polyline encoded string.

If the specified area and vehicle parameters are such that the only possible route is through the avoided area, the part of the route inside the avoided area may not be optimal. Scenarios in which the route may go through an avoided area:

• An alternate route can't be calculated because the only bridge that connects the origin region and the destination region is in the avoided area.
• Origin, destination or intermediate waypoint is in the avoided area.

Small and large area avoidance

• For performance considerations different algorithms are used for avoiding areas based on the size of these areas, hence distinguishing between small and large areas. The avoidance algorithm performs Segment geometry based avoidance for small areas and switches to segment-junction(start/end)-based approximate avoidance for large areas.
• The segment-geometry-based avoidance for small areas is able to avoid segments which are partially inside the area. But the segment-junction-based approximate avoidance for large areas will only avoid segments completely inside the area, or if a start or an end junction is inside the area. Sometimes the approximate avoidance algorithm for large areas may avoid segments partially inside the area, but this isn't guaranteed for all cases. So, when using large areas it's recommended that the area covers the entire segment that is intended to be avoided.
• For practical purposes, the avoidance algorithm considers a region comparable in size (width in both dimensions and area) to a few city blocks as a small area. For example, the average city block size in Manhattan or Chicago is approximately 20000 square meters and a Paris city block is around 5 to 7 hectares or 50000-70000 square meters. A small area is useful in avoiding specific blocks, road portions, or intersections those might be congested or temporarily restricted, for example during sporting events or political conventions.
• Regions comparable in size to city neighborhoods (Cobble Hills, Brooklyn Heights in New York), restricted zones (Berlin's Environmental Zone, London Ultra Low Emission Zone), long corridors (multiple kilometers) along a road stretch, administrative divisions (borough, district, village, town, city, state), are all treated as large areas.
• For details related to how small vs large area avoidance works for different area types (bbox, polygon, corridor) refer to the small vs large area avoidance example.

Example that avoids a bounding box area

This request avoids going through a bounding box area in the Tiergarten park:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.522297,13.353296&'\
'destination=52.508309,13.355633&'\
'transportMode=car&'\
'avoid[areas]=bbox:13.37588,52.51061,13.34226,52.51892&'\
'apiKey=YOUR_API_KEY'

The resulting route takes a detour to avoid the specified area.

Example that avoids a polygon area

This request avoids going through a polygon area in the Tiergarten park:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.522297,13.353296&'\
'destination=52.508309,13.355633&'\
'transportMode=car&'\
'avoid[areas]=polygon:52.518591,13.341621;52.52379,13.373352;52.511903,13.378032;52.506228,13.333503&'\
'apiKey=YOUR_API_KEY'

Example that avoids multiple areas

One of the use case for avoiding multiple areas is with tour planning. For example, the user may want to do tour planning for future without using time and traffic, but the user is sure of some areas where most of the time there is heavy traffic or areas that they don't feel safe to travel. The user can use multiple avoid areas feature to avoid all of them.

This request avoids three areas (a bounding box area, a corridor area, and a polygon area):

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.560708,13.375166&'\
'destination=52.591865,13.425968&'\
'return=polyline,summary,actions,instructions&'\
'transportMode=car&'\
'avoid[areas]=corridor:52.574814,13.389686;52.57986,13.397721;r=100|bbox:13.414203,52.584536,13.408161,52.588353|polygon:52.569582,13.403511;52.564922,13.407161;52.561504,13.411367;52.559166,13.412932;52.565349,13.412113;52.568835,13.411635;52.570998,13.410085&'\
'apiKey=YOUR_API_KEY'

It can be seen from the image that the route avoids going through the areas marked for avoidance.

Example of using an exception to an avoid area

Each avoid area can be extended with one or more exception areas. Exception areas are excluded from the associated avoidance area: avoid[areas]={area}!exception={area1}[!exception={area2}]...

This request avoids going through a polygon area in the Tiergarten park, but allows going through a specific corridor within this avoid area:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.522297,13.353296&'\
'destination=52.508309,13.355633&'\
'transportMode=car&'\
'avoid[areas]=bbox:13.37588,52.51061,13.34226,52.51892!exception=corridor:52.52337773,13.35671004;52.51713813,13.35452568;52.51451650,13.35003559;52.50583814,13.35209860;r=100&'\
'apiKey=YOUR_API_KEY'

Example of avoid areas with a violation notice

This request fails to avoid the specified area, because the destination is inside the area to be avoided.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.514647,13.387549&'\
'destination=52.516547,13.379095&'\
'transportMode=car&'\
'avoid[areas]=bbox:13.382279,52.51441,13.376397,52.518284&'\
'apiKey=YOUR_API_KEY'

The response specifies a notice with the code violatedBlockedRoad:

{
  "routes": [
    {
      "id": "a394029a-06c3-4864-b46c-8296acfcf6a1",
      "sections": [
        {
          ...,
          "notices": [
            {
              "title": "Violated road that is blocked, due to a traffic incident, `avoid[areas]`, or `avoid[segments]`.",
              "code": "violatedBlockedRoad",
              "severity": "critical"
            }
          ],
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

To learn more about notices, see this topic.

Example of small vs large area avoidance

Whether an area is processed as a small or a large area depends on the size of the bounding box of the area. This applies to both the area being avoided and the exception area. For example, a long, narrow corridor or polygon will have different bounding boxes depending on how it's oriented. The bounding box of any area type (bbox, corridor, polygon) is only used to identify them as a small or a large area. The avoidance algorithm (that is, whether a segment is inside or outside the area) is based on the actual area, not the bounding box of the area. For an area of type bbox the actual area and bounding box of the area are the same, but this may not be true for corridor and polygon types (as it depends on their shape and orientation).

This route passes through a 1200-meter-long segment (highlighted between green markers) on the Brooklyn-Queens Expressway, New York, USA.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=40.697049,-73.989433&'\
'destination=40.699537,-73.942296&'\
'return=polyline,summary,actions,instructions&'\
'spans=notices,segmentRef,length&'\
'transportMode=car&'\
'departureTime=any&'\
'apiKey=YOUR_API_KEY'

The examples in the following sections show what happens when you try to avoid the highlighted segment using different kinds and sizes of avoid area.

Large bbox covers segment partially

This request uses a large area (bbox) which covers the segment partially but not the junctions. This results in the segment not being avoided as approximate junction-based avoidance is used.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=40.697049,-73.989433&'\
'destination=40.699537,-73.942296&'\
'return=polyline,summary,actions,instructions&'\
'spans=notices,segmentRef,length&'\
'transportMode=car&'\
'departureTime=any&'\
'avoid[areas]=bbox:-73.97213,40.675754,-73.97728,40.697551&'\
'apiKey=YOUR_API_KEY'

Large bbox covers segment junction

This request uses a large area (bbox) which covers a segment-junction. This results in the segment being avoided as approximate avoidance uses junctions.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=40.697049,-73.989433&'\
'destination=40.699537,-73.942296&'\
'return=polyline,summary,actions,instructions&'\
'spans=notices,segmentRef,length&'\
'transportMode=car&'\
'departureTime=any&'\
'avoid[areas]=bbox:-73.97728,40.675689,-73.98243,40.697486&'\
'apiKey=YOUR_API_KEY'

Small bbox covers segment partially

This request uses a small area (bbox) which covers a segment partially. This results in the segment being avoided as exact segment-geometry-based avoidance is used.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=40.697049,-73.989433&'\
'destination=40.699537,-73.942296&'\
'return=polyline,summary,actions,instructions&'\
'spans=notices,segmentRef,length&'\
'transportMode=car&'\
'departureTime=any&'\
'avoid[areas]=bbox:-73.97213,40.695409,-73.97728,40.696711&'\
'apiKey=YOUR_API_KEY'

Large corridor covers segment partially

This request uses a large area(long corridor) which covers a segment partially. This results in the segment not being avoided, as approximate junction based avoidance is used and the segment junctions aren't covered.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=40.697049,-73.989433&'\
'destination=40.699537,-73.942296&'\
'return=polyline,summary,actions,instructions&'\
'spans=notices,segmentRef,length&'\
'transportMode=car&'\
'departureTime=any&'\
'avoid[areas]=corridor:40.687463,-73.990582;40.703992,-73.963288;r=50&'\
'apiKey=YOUR_API_KEY'

Small corridor covers segment partially

This request uses a small area(short corridor) which covers a segment partially. This results in the segment being avoided, as exact segment-geometry-based avoidance is used.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=40.697049,-73.989433&'\
'destination=40.699537,-73.942296&'\
'return=polyline,summary,actions,instructions&'\
'spans=notices,segmentRef,length&'\
'transportMode=car&'\
'departureTime=any&'\
'avoid[areas]=corridor:40.695143,-73.977793;40.697095,-73.975132;r=500&'\
'apiKey=YOUR_API_KEY'

Large polygon covers segment completely

This request uses a large area(polygon) which covers a segment completely. This results in the segment being avoided, as the entire segment is inside the avoided area.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=40.697049,-73.989433&'\
'destination=40.699537,-73.942296&'\
'return=polyline,summary,actions,instructions&'\
'spans=notices,segmentRef,length&'\
'transportMode=car&'\
'departureTime=any&'\
'avoid[areas]=polygon:40.697557,-73.981282;40.68812,-73.981883;40.686754,-73.957078;40.697231,-73.956391&'\
'apiKey=YOUR_API_KEY'

📘

Note

Sometimes the approximate avoidance algorithm for large areas may avoid segments partially inside the area, but this isn't guaranteed for all cases. When using large areas it's recommended that:

• The area covers the entire segment that should be avoided.
• The area doesn't partially cover any segment that shouldn't be avoided.
• If because of complicated geometry a large area ends up partially covering a segment which shouldn't be avoided and this results in the segment getting unintentionally avoided, then exception corridors or polygons could be used.

Example that avoids a bounding box using a POST request

When sending a request with many avoid[areas] parameters, your GET request may exceed the maximum number of characters allowed. In such cases, you may wish to send a POST request, using the avoid parameter in the POST body.

This request adds a boundingBox area to the post body avoid option, which results in the route taking a longer path (blue path in the image) and avoiding the shorter path (purple path in the image).

curl -gX POST 'https://router.hereapi.com/v8/routes?'\
'origin=48.830254,2.352944&'\
'destination=48.837851,2.360125&'\
'return=polyline,summary&'\
'transportMode=scooter&'\
'departureTime=any&'\
'apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' -d '
{
  "avoid": {
    "areas": [
      {
        "type": "boundingBox",
        "west": 2.352272,
        "south": 48.830508,
        "east": 2.357164,
        "north": 48.833276
      }
    ]
  }
}
'

For examples of how to specify other types of areas along with exceptions in the post body, refer to the avoid area post body examples in the API reference.