Traffic API Developer's Guide

Incidents

This resource is responsible for handling requests for traffic incident information for or a geospatial area. The delivery formats are either XML or JSON. The below provided request parameters are valid for both incident endpoints (6.0 and 6.1)*.

(* one exception is the type parameter. For mor details see description for this parameter.)

Parameter Combinations for Common Use Cases

Table 1. Request Traffic Incident Data Using Localization
Required Optional
  • quadkey, prox, bbox , or corridor (except with Z/X/Y address)
  • c and lg as a pair or with i18n
  • criticality
  • endTime
  • inc22
  • jsoncallback
  • localtime
  • maxresults
  • profile
  • sort
  • startTime
  • status
  • tables
  • type
  • verified
  • units
Table 2. Request a Subset of Traffic Incident Data
Required Optional
  • quadkey, prox, bbox , or corridor (except with Z/X/Y address)
  • One or more of these filter parameters:
    • criticality
    • endTime
    • maxresults
    • profile
    • startTime
    • status
    • tables
    • type
    • verified
  • c and lg as a pair or with i18n
  • inc22
  • jsoncallback
  • localtime
  • sort
  • units

Response Data Format

This resource can deliver response data either in XML of JSON, depending on the addressing scheme:

  • [Z]/[X]/[Y] addressing – use the URL variables xml or json, immediately after the resource name, for example .../flow/xml/... or .../incidents/json/...
  • otherwise – use resource extensions .xml or .json, for example .../flow.json/..., .../incidents.xml/...

See also Examples for complete working URLs.

Resource Parameters

Table 3. Incident Request Parameters
Parameter Description
app_code

xs:string

A 20-byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request. For further details, see Acquiring Credentials.

app_id

xs:string

A 20-byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request.  For further details, see Acquiring Credentials.

bbox

GeoBoundingBoxType: lat,lon; lat,lon

A type of spatial filter. A spatial filter defines the area targeted by the request (the area for which to retrieve data or a map tile).  A bounding box represents a rectangular area specified by two latitude/longitude pairs;  the first pair defines the top-left corner of the bounding box, the second the bottom-right corner.

Note: The maximum allowed size of the bounding box (width and height) is limited to a configurable value expressed in degrees. The default maximum values for the width and height of a bounding box is 10 degrees.
c

xs:string

An indicator of the country (locale for the incident response). The accepted values include certain ISO country codes (two bytes, ISO 3166-1-alpha-2). The parameter must be used in conjunction with the lg parameter. By default (if the parameter is not specified), the time and format of the response are based on the location of the incident.

corridor

GeoCorridorType: lat,lon; lat,lon; lat,lon; lat,lon; [etc.]; width

A type of spatial filter. A spatial filter defines the area targeted by the request (the area for which to retrieve data or a map tile). The response to a corridor request includes results that fall within the area of the corridor. The corridor is defined by its path and width. The path is a line along the center of the corridor represented by a series of latitude/longitude pairs. Corridor width is given in meters.

criticality

xs:string

A filter that selects incident reports according to criticality, case insensitive. The parameter may contain multiple comma-separated values selected from the following list:

  • critical or 0
  • major or 1
  • minor or 2
  • lowImpact or 3

Note that if this parameter is not provided, all incident reports are included in the response, regardless of criticality (default behavior).

endTime

xs:dateTime

The maximum end time that must be matched by an incident to be included in the results, in GMT format.
YYYY-MM-DDThh:mm:ss.s+zzzz
See xs:dateTime for the format to use when filtering time values.
i18n

xs:boolean

A flag indicating whether incident messages should be translated to the language specified in the lg parameter. The parameter must be used in conjunction with the lg.

The permitted values for the parameter are:

  • true
  • false
inc22

xs:boolean

A flag indicating whether to format the response to match version. 2.2 of the incidents XSD (true). Version 2.2 of the XSD contains fields and information not included in the default version 2.1 (5.0)

The permitted values are:

  • true or 1
  • false or 0
jsoncallback

xs:string

A parameter providing the name of a user-defined function used to wrap the JSON response.

lg

xs:string

A specifier of the language of the locale for the incident response. The parameter must be used in conjunction with the c parameter. By default (if lg is not provided), the language of the response is based on the incident location.

See Supported Translation Languages for allowed values.

localtime

xs:boolean

A flag indicating if all time values in the response to a request for traffic incident data should be in the local time of the incident (true), instead of GMT +h:mm (false). The permitted values are:

  • true or 1
  • false or 0
maxresults

xs:int

An indicator of the maximum number of incidents to be included in the response. Only non-zero positive number values are allowed.

profile

xs:string

Profile defines such attributes as geographic coverage (TMC tables available for use) and custom color mapping for tile overlays.

prox

GeoProximityType: lat,long,distance

A type of spatial filter. A spatial filter defines the area targeted by the request (the area for which to retrieve data or a map tile). A response to a request using proximity includes any results that fall within a circle defined by the a latitude and a longitude of its center and radius (given in meters).

quadkey

QuadkeyType

An identifier of a map tile in a grid of tiles spanning the entire globe. A quadkey is a single number string from 0 to 21 digits long. The map zoom level for the grid to which a quadkey refers is equal to the number of digits in the quadkey string. Use only with a quadkey addressing scheme endpoint. See also Quadkeys.

sort

xs:string

An indicator, specifying how to sort the response data to a traffic incident request according to criticality. The permitted values are:

  • criticalityDesc
  • criticalityAsc
startTime

xs:dateTime

The minimum start time to be matched by an incident to be included in the results, in GMT format.
YYYY-MM-DDThh:mm:ss.s+zzzzzz
See xs:dateTime for the format to use when filtering time values.
status

xs:string

A status indicator that triggers incident selection according to their status; case insensitive. The parameter value may consist of multiple values, separated by a comma. The accepted status values include: active, inactive, deleted, and expired. By default (when the parameter is not specified) the response includes all incident reports, regardless of status.

tables

TMCCodeType

A parameter that specifies TMC tables in the profile to include or exclude from response. If the value specifies multiple tables, the table ids are separated by commas. Positive values are included, and negative values are excluded.
Note: A combination of positive and negative values is not supported and results in an error response.
By default (when the parameter is not used in a request) the response includes all tables in the profile. See TMCCodeType for a full list of TMC tables or your customer profile for a list of tables available to you.
type

xs:string

An indicator, specifying the type of items to include in the response, case insensitive. The value may contain multiple type identifiers separated by a comma. The permitted traffic item type identifiers that can be used in the value are:

  • Accident
  • Congestion
  • DisabledVehicle
  • RoadHazard
  • Construction
  • PlannedEvent
  • MassTransit
  • OtherNews
  • Weather
  • Misc
  • RoadClosure *
  • LaneRestriction *

By default (when the parameter is not specified in the request), the response includes all incident reports, regardless of type.

* - This type is supported only when requesting incidents ver 2.2 (traffic/6.1/incidents.<format> endpoint)

verified

xs:boolean

A flag indicating if the response is to include or exclude incident reports that have been confirmed. The permitted values are:

  • true or 1
  • false or 0

By default, when this parameter is not specified in the request, the response includes all incident reports, regardless of type.

units

xs:string

This parameter is used to assure that all values in the response are converted to the needed Units system.

Accepts the following values:

  • metric
  • imperial

By default, when this parameter is not specified, values are returned in the same Unit system as it was received from Content feed.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.