Jump to Content

What is a notice

Notices are elements of the API response that carry warning or error messages regarding the calculated route or the requested calculation. They can appear on the top level of the API response to convey information applicable to the entire request, or in route sections, where they signal issues found in the specific parts of the route.

The following are example notices:

noRouteFound - The route calculation request with the specific parameters failed.
violatedVehicleRestriction - A part of the calculated route violates a vehicle-specific restriction, such as a maximum weight limit for trucks.
violatedAvoidTunnel - A part of the calculated route fails to avoid tunnels, which was one of the requirements set in the route calculation request.

Notice format

The following example notice contains all attributes that a notice can have. The number of attributes varies depending on the notice type.

{
  "title": "Violated vehicle restriction.",
  "code": "violatedVehicleRestriction",
  "severity": "critical",
  "details": [
    {
      "type": "restriction",
      "cause": "Route violates vehicle restriction",
      "maxGrossWeight": 5000,
      "maxWeight": {
      "value": 5000,
      "type": "gross"
      }
    }
  ]
}

Attribute	Description
`title`	Human-readable string that supplements the `code` attribute.
`code`	Enumerated string that indicates the notice type.
`severity`	Enumerated string that indicates how serious a notice is. One of `info` or `critical`
`details`	Object that carries additional information for the specific notice.

📘
Note
Routes that contain critical severity level notices should be used only after a thorough evaluation and consideration of the impact of the violated restrictions. With updates of the API, new critical severity level notices can be added and route calculations that previously failed can return routes with new notice codes. It's recommended to discard such routes.

Locate notices on the route

To learn where exactly on the calculated route a notice applies, use the spans=notices option in the route calculation request. This returns spans with a notices array with a list of indexes into the notices array of the parent section.

See the following example request and its response (truncated):

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=51.019519,17.161546&'\
'destination=51.108671,17.038804&'\
'return=polyline&'\
'spans=notices&'\
'transportMode=truck&'\
'vehicle[grossWeight]=12000&'\
'vehicle[height]=400&'\
'apiKey=YOUR_API_KEY'

{
  "spans": [
    {
      "offset": 0
    },
    {
      "offset": 438,
      "notices": [
        0
      ]
    },
    {
      "offset": 462,
      "notices": [
        0,
        1
      ]
    }
  ],
  "notices": [
    {
      "title": "Violated vehicle restriction.",
      "code": "violatedVehicleRestriction",
      "severity": "critical",
      "details": [
        {
          "type": "restriction",
          "cause": "Route violates vehicle restriction",
          "maxGrossWeight": 9000,
          "maxWeight": {
            "value": 9000,
            "type": "gross"
          }
        }
      ]
    },
    {
      "title": "Violated vehicle restriction.",
      "code": "violatedVehicleRestriction",
      "severity": "critical",
      "details": [
        {
          "type": "restriction",
          "cause": "Route violates vehicle restriction",
          "maxGrossWeight": 3500,
          "maxWeight": {
            "value": 3500,
            "type": "gross"
          },
          "timeDependent": true,
          "restrictedTimes": "++(h0){h6}(h9){h9}(h22){h2}"
        }
      ]
    }
  ]
}

Related content

Updated last month