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 more 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 more information on authentication, see the Identity & Access Management Developer Guide.
`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 more information on authentication, see the Identity & Access Management Developer Guide.
`apiKey`	`xs:string` A 43-byte Base64 URL-safe encoded string used for the authentication of the client application. As a logged in user, you can generate it at https://developer.here.com/projects. API Keys never expire but you can invalidate your API Keys at any time. You cannot have more than two API Keys for one app at the same time. You must include an `apiKey` with every request. For more information on authentication, see the Identity & Access Management Developer Guide.
`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 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.