How to exclude territories from routing

The exclude[countries], exclude[states], and exclude[areas] parameters allow you to calculate routes that exclude specific territories from routing. Use these parameters to ensure that the route never goes through these states, countries, or custom areas.

For example, if the origin or destination of the route is in an excluded territory, the route calculation fails.

Exclude countries

In this example, the route calculation request uses the exclude[countries] parameter to exclude Switzerland from route calculation.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=45.474427,9.138537&'\
'destination=50.096988,8.66033&'\
'return=polyline&'\
'transportMode=car&'\
'exclude[countries]=CHE&'\
'apiKey=YOUR_API_KEY'

The blue route excludes Switzerland. The purple route shows the result without exclude[countries]=CHE.

Exclude states

You can exclude territories at the state level using the exclude[states] parameter. State exclusion is supported in selected countries. For a full list, see Countries which support state exclusion.

In this example, the route calculation request from Tucumcari to Oklahoma City excludes the state of Texas.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=35.171888,-103.724999&'\
'destination=35.46546193,-97.52597214&'\
'return=polyline&'\
'transportMode=car&'\
'exclude[states]=USA:TX&'\
'apiKey=YOUR_API_KEY'

The purple route excludes Texas. The blue route shows the result without exclude[states]=USA:TX.

Exclude areas

Use the exclude[areas] parameter to exclude one or more custom geographic areas from route calculation. This is useful when you want to avoid a specific zone that isn't defined by administrative boundaries, such as a construction zone or a restricted area.

The following area types are supported:

Bounding box — a rectangular area defined by its west, south, east, and north coordinates. Format: bbox:{west},{south},{east},{north}
Polygon — an arbitrary polygon defined as a list of {lat},{lon} pairs separated by semicolons, or as a Flexible Polyline encoded string. Format: polygon:{lat},{lon};{lat},{lon};...
Corridor — a polyline with a radius (in meters) that defines a band around the line. Format: corridor:{lat},{lon};{lat},{lon};...;r={radius}

Separate multiple areas with |.

Limitations:

Maximum 250 excluded areas in total (including exceptions).
Within that total, a maximum of 20 can be polygons and corridors combined. The remaining areas can be bounding boxes.

In this example, the route calculation excludes the bounding box area of central Berlin.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.3739,13.0582&'\
'destination=52.6755,13.7606&'\
'return=polyline&'\
'transportMode=car&'\
'exclude[areas]=bbox:13.082,52.416,13.628,52.626&'\
'apiKey=YOUR_API_KEY'

Exclude multiple areas

Separate the areas with | and list them as a single exclude[areas] value.

In this example, two areas around Berlin are excluded from route calculation.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.3739,13.0582&'\
'destination=52.6755,13.7606&'\
'return=polyline&'\
'transportMode=car&'\
'exclude[areas]=bbox:13.082,52.416,13.628,52.626|bbox:13.53,52.28,13.72,52.43&'\
'apiKey=YOUR_API_KEY'

Exceptions

You can mark a sub-area within an excluded area as an exception, so that the router is still allowed to pass through it. Append !exception={area} to the area definition.

In this example, an area around Berlin is excluded, but an exception allows the destination inside that area to still be reached.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.530,12.900&'\
'destination=52.513831,13.475821&'\
'return=polyline&'\
'transportMode=car&'\
'exclude[areas]=bbox:13.082,52.416,13.628,52.626!exception=bbox:13.082,52.5,13.628,52.56&'\
'apiKey=YOUR_API_KEY'

No detour available

When excluding territories, HERE Routing API v8 reliably offers detours that honor the user's exclusion settings. There are, however, limits to the API's ability to calculate detours. One such example is calculating a route from Berlin to Vilnius while avoiding Poland.

Run this sample request to see that the calculation fails:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.494438,13.40415&'\
'destination=54.679577,25.254137&'\
'return=polyline&'\
'transportMode=car&'\
'exclude[countries]=POL&'\
'apiKey=YOUR_API_KEY'

Next steps

See the API Reference to learn more about using the exclude parameter.
See Avoidance to learn about avoidance in routing, which is less strict than excluding territories.