Incidents

Incident data provides information about discrete events that affect specific sections of a roadway. Some examples of events are closures, road works, and accidents.

Request parameters

There are two mandatory request parameters when retrieving flow or incident data:

• in - geospatial filter
• locationReferencing - location references to be returned

For more information about how to use these parameters, see Geospatial filters and Location referencing.

Additionally, there are further optional filter parameters:

• functionalClasses filters the locations in the response by the Functional Road Class of the roadway that is represented. For further details, see the flow use case Filter Incidents by Functional Class.
• criticality filters by the incident criticality field
• type filters by the incident type field
• earliestStartTime and latestEndTime filter by the incident startTime and endTime fields respectively

The lang parameter is used to request that the incident description and summary fields are returned in a specific language. For more information, see Request incidents in a different language.

Request incident by ID

A request can also be made for a single incident by ID. The value of the originalId field should be used (See IDs below for more information on the available fields). In this case, only the locationReferencing parameter is mandatory and the in parameter cannot be used.

For further details, see the incidents use case Request Incident by ID.

Response data model

The response from the incidents endpoint provides a list of incident objects together with the last updated time of the source data.

When an incident is requested by ID, then a single incident object is returned instead of a list.

Each incident object consists of a location field containing a location reference and an incidentDetails field containing the specific details of the incident.

The location reference object is described under Location Referencing.

IDs

Each incident may have a number of IDs attached.

• id - identifier for the incident version; may change on updates to the same incident.
• originalId - identifier of the first incident in a chain of updates. This value is stable across updates to the incident.
• parentId - identifier of another incident to which this incident is linked. For example, if the incident is a congestion item caused by an accident, this identifier would refer to the accident incident.

Codes and type

Each incident contains two fields that specify what event the incident represents.

The type field is an enumerated value that gives a general group for the incident. This enum may be extended in the future. The current values are:

• accident - indicates that there has been a collision
• construction - indicates that building or roadworks are taking place
• congestion - indicates that there has been a build-up of vehicles
• disabledVehicle - indicates that a vehicle is unable to move and is obstructing the road
• massTransit - indicates that an event is present related to public transit
• plannedEvent - indicates that an organised event is taking place causing disruption
• roadHazard - indicates that there are dangerous objects on the surface of the road
• roadClosure - indicates that the road has been closed, for example, by the police
• weather - indicates that weather conditions are causing disruptions
• laneRestriction - indicates that some of the lanes have access restrictions
• other - indicates that an incident not explainable with the types above has occurred

The codes field gives a prioritized list of codes that describe the cause of the incident according to the AlertC specification.

The codes are given in order of importance, so the first item in the list is considered the primary cause of the incident.

The full list of codes in the AlertC specification can be found in ISO 14819-2:2013.

Criticality

The criticality field represents the severity of the incident. It has the following values:

• low - least severe
• minor
• major
• critical - most severe

Criticality can be used to provide visual indications for a user interface, but no further information should be inferred from its value.

Times

An incident may have up to three time fields. All fields are formatted as per RFC 3339, Section 5.6 as defined by date-time. The times are always given in UTC explicitly (strings end in Z).

• startTime - the time from which the incident is valid, before this time the incident should not be considered.
• endTime - the time until which the incident is valid, after this time the incident should not be considered.
• entryTime - the time the incident was entered into the system.

Road closed

The incident will always contain a flag roadClosed to indicate whether the incident prevents travel along the roadway.

Junction traversability

Indicates junction traversability. Used for road closures to indicate if the junctions along the closure can be crossed.

• allOpen - all junctions are open
• allClosed - all junctions are closed
• intermediateClosedEdgeOpen - junctions at beginning and end of the roadway are open, intermediate junctions are closed
• startOpenOthersClosed - first edge junction is open, all others are closed
• endOpenOthersClosed - last edge junction is open, all others are closed

The default value is allOpen and the field will only be present if the value differs from this default.

Restrictions

A list of restrictions applied to vehicles that can traverse the specified roadways. The restrictions are temporary and apply as long as the incident is present. If a vehicle falls under the conditions of the restriction, it's not allowed to pass through that area.

Each restriction in the list has a vehicle type and a restriction type. The current values for vehicle type are:

• bus
• car
• heavyGoodsVehicle
• lorry
• motorcycle
• motorVehicle
• taxi
• train
• transportingAnAbnormalSizeLoad
• transportingHazardousGoods
• vehicleWithTrailer
• other

Restriction types can be one of the following:

• sizeRestriction - a restriction vehicles that can pass through an area based on either the height, length, or width of the vehicle measured in centimeters. This restriction has a dimension field that defines to which dimension the restriction applies, and a value field that defines the restriction value with either lessThan or greaterThan labels.
• weightRestriction - a restriction on the weight of the vehicle in kilograms that can pass through an area. This restriction has a weight_type field that defines the weight type to be either weightPerAxle or grossWeight, and a value field that defines the value with either lessThan or greaterThan labels.
• vehicleOccupancyRestriction - a restriction on the number of passengers in the vehicle that can pass through an area. It has a single value with either lessThan or greaterThan labels.
• emissionRestriction - a restriction on the emission class of the vehicle. Possible values are:
  • emissionEuro3
  • emissionEuro3d4
  • emissionEuro4
  • emissionEuro5
• equipmentTypeRestriction - a restriction on the vehicle's equipment. Possible values are:
  • withCaravan
  • withTrailer
  • withoutSnowChains
  • withoutWinterTyres
• fuelTypeRestriction - a restriction on the vehicle's fuel type. Possible values are:
  • diesel
  • lpg
  • petrol
• TrafficTypeRestriction - a restriction on the type of traffic. Possible values are:
  • residentsTraffic
  • throughTraffic
  • noThrough
• plateNumberRestriction - a restriction on the vehicle's plate number. Possible values are:
  • evenNumberPlate
  • oddNumberPlate

Summary and description

Each incident contains two textual fields describing the incident in human-readable language. These fields are appropriate to be displayed to an end user.

The summary field provides a short version of the description containing no location information.

Example summaries:

• "Construction work. Lane blocked."
• "No through traffic."
• "Closed due to roadwork."

The description field provides a longer textual description, possibly with location information.

Example descriptions:

• "Between Foster City Blvd and San Mateo County Fishing Pier - Construction work. Lane blocked."
• "Between Shattuck Ave and Howell St - No through traffic"
• "At I-80/Miller Ave - Closed due to roadwork."