How to avoid segments in routes

A segment is a topology segment that represents a section of road or an otherwise linear, navigable stretch (see Segment).

Many use cases may require a creation of temporary user-specific routes, which avoid specific segments that the route would otherwise pass through. This might be, for example, a driver seeing that the road in front is now blocked due to a mishap, or the planner knowing that the particular street is to be avoided for their vehicle due to size limitations.

The avoid[segments] feature allows users to request such routes.

The following tutorial will describe how to get information about and avoid segments, with some examples.

📘

Note

Up to 1000 segments can be specified for avoiding (using POST). Up to 250 segments are counted as part of the regular transaction. 251 to 500 segments in the avoid list incur an additional routing transaction in the monthly transaction count. 501 to 750 segments will incur 2 additional transactions and 751 to 1000 will incur 3 additional transactions.

Avoid segment from the returned route

If a route is calculated with the span=segmentRef specified, the returned route (blue line at Figure 1) would include a list of segment spans.

The following command can be used to calculate a list of segment spans between the given origin and destination:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=45.484661,9.228382&'\
'destination=45.485542,9.234576&'\
'return=polyline&'\
'spans=segmentRef&'\
'transportMode=car&'\
'apiKey=YOUR_API_KEY'

It returns the following list of segment spans:

{
  "routes": [
    {
      "sections": [
        {
          "type": "vehicle",
          ...,
          "polyline": "BG8vl42CwvqzR8D4X0FgoB8Lk1B0FwbqEoR",
          "refReplacements": {
            "0": "hrn:here:data::olp-here:rib-2:3217:",
            "1": "here:cm:segment"
          },
          "spans": [
            {
              "offset": 0,
              "segmentRef": "$0:377570872:$1:76764732#+0.6376674544619554..1"
            },
            {
              "offset": 1,
              "segmentRef": "$0:377570872:$1:89214839#+0..1"
            },
            {
              "offset": 2,
              "segmentRef": "$0:377570872:$1:95058600#+0..1"
            },
            {
              "offset": 3,
              "segmentRef": "$0:377570872:$1:82740696#+0..1"
            },
            {
              "offset": 4,
              "segmentRef": "$0:377570872:$1:96835127#+0..0.626940133196055"
            }
          ],
          "transport": {
            "mode": "car"
          }
        }
      ]
    }
  ]
}

The segment at offset 2 has segmentId and direction specified as $1:95058600#+, which converts to here:cm:segment:95058600#+ with the help of the refReplacement parameter. If this segment has to be avoided in both directions, then the route request should include avoid[segments]=here:cm:segment:95058600, without the direction part:

📘

Note

More on constructing the complete HRN using refReplacement is described on the Referencing HERE Map Content entities page.

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=45.484785,9.229564&'\
'destination=45.485299,9.232146&'\
'avoid[segments]=here:cm:segment:95058600&'\
'return=polyline&'\
'spans=segmentRef&'\
'transportMode=car&'\
'departureTime=any&'\
'apiKey=YOUR_API_KEY'

And the returned route with avoidance (purple line at Figure 1) would go around the avoided segment.

Calculating a tiny route over one or few segments would allow to learn the ID of those segments and their direction, when those segments are a part of the route.

Avoid segment of the map in the specific direction

Assume a user would like to avoid traveling a certain road in a certain direction, for example, from east to west (see Figure 2).

When fetching this segment from the map (see Segment), the user gets a segment ID, the associated geometry and the start and end nodes:

{
  "identifier": "here:cm:segment:95058600",
  "geometry": [
    {
      "latitude": 45.48495,
      "longitude": 9.23058,
      "z_level": 0,
      "elevation": 0
    },
    {
      "latitude": 45.48514,
      "longitude": 9.23143,
      "z_level": 0,
      "elevation": 0
    }
  ],
  "length": 69.72647,
  "startNode": {
    "identifier": "here:cm:node:66488603",
    "geometry": {
      "latitude": 45.48495,
      "longitude": 9.23058,
      "z_level": 0,
      "elevation": 0
    }
  },
  "endNode": {
    "identifier": "here:cm:node:66488604",
    "geometry": {
      "latitude": 45.48514,
      "longitude": 9.23143,
      "z_level": 0,
      "elevation": 0
    }
  }
}

Positive direction of the segment corresponds to travelling from the start node to the end node. Since longitude of the start node is smaller than of the end node, then positive direction corresponds to travelling from west to east. To avoid traveling on this segment from east to west this segment should be avoided in the negative direction avoid[segments]=here:cm:segment:95058600%23-:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=45.485299,9.232146&'\
'destination=45.484785,9.229564&'\
'avoid[segments]=here:cm:segment:95058600%23-&'\
'return=polyline&'\
'spans=segmentRef&'\
'transportMode=car&'\
'departureTime=any&'\
'apiKey=YOUR_API_KEY'

Avoid segment using a POST request

When sending a request with many avoid[segments] 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 segment to the post body avoid option, which results in the route avoiding the bridge (highlighted segment in the below image) and taking a longer path.

curl -gX POST 'https://router.hereapi.com/v8/routes?'\
'origin=52.517783,13.38846&'\
'destination=52.516158,13.402718&'\
'return=polyline,summary&'\
'transportMode=truck&'\
'vehicle[grossWeight]=20000&'\
'vehicle[height]=600&'\
'vehicle[trailerCount]=1&'\
'departureTime=2024-09-13T13:32:43+02:00&'\
'apiKey=YOUR_API_KEY' \
  -H 'Content-Type: application/json' -d '
{
  "avoid": {
    "segments": [
      "here:cm:segment:141874221"
    ]
  }
}
'