Traffic API Developer's Guide

Includes

Resource Request Parameters

Table 1. Resource Request Parameters
Parameter Description
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.

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.

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 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 10 degrees.
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 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.

responseattributes

xs:list

A container for a list indicating optional information to be included in the traffic flow data response. By default, the response does not include shape or functional class information, unless indicated by this parameter. The accepted value is a list of the following specifiers:

  • sh or shape
  • fc

See Bounding Box Filter for an example request using the responseattributes parameter.

locationreferences

xs:list

A container for a list indicating optional information to be included in the traffic flow data response. By default, the response does not include DLR information, only TMCs are returned. The accepted value is a list of the following specifiers:

  • shp
  • tmc
minjamfactor

xs:double

An indicator of the minimum jam factor value for traffic flow items to be included in the response. All flow events with a lower jam factor than the value specified by the minjamfactor parameter are omitted. The parameter can be used by clients that require flow data for congested roadways only. The value must be in the range 0.0 to 10.0 (inclusive).

maxjamfactor xs:double

An indicator of the maximum jam factor value for traffic flow items to be included in the response. All flow events with a higherjam than the value specified by the maxjamfactor parameter are omitted. This parameter can be used by clients that require flow data only for congestion-free roads. The values must be in the range 0.0 to 10.0 (inclusive).

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).

depth

xs:string

An indicator of tile color depth. The permitted values are:

  • 8bit
  • 32bit

Used only with quadkey tile addressing.

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.
format

xs:string

An indicator of the format of the response to a traffic incident request, either xml or json.

id

xs:int

A user-defined incident identifier. The response contains the specific incident requested. Any integer is allowed.

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.

mapview

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).   mapview defines the area to check for traffic coverage in the same way as bbox, following the same pattern and rules.

If this parameter is not specified, the response returns all countries supported by the specified profile.

maxfunctionalclass

xs:int

An indicator of the maximum functional class that must be matched for a traffic flow item to be included in the response. All items with functional class lower than or the same as the value of this parameter are included in the response. For more details about functional class, see FunctionalClassType.

negBBox

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). Negative bounding box requests exclude results within a negbbox, 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 that negative filters cannot be combined with other negative filters in the same request.

negCorridor

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). A response to a negative corridor request excludes any search 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.

Note that negative filters cannot be combined with other negative filters in the same request.

negProx

GeoProximityType: lat,long,radius

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 negative proximity excludes any results that fall within a circle defined by the a latitude and a longitude of its center and radius (given in meters).

Note that negative filters cannot be combined with other negative filters in the same request.

nc

xs:int

A flag indicating whether the response is to return HTTP error code 204 (empty) for unpopulated traffic tiles (1).

The permitted values are:

  • 1
  • 0
pattern_time

xs:int

An indicator of the time (within the week) for which to obtain a traffic pattern tile. The value represents local time for the targeted area, in seconds beginning on Sunday at 0:00. The permitted values are numeric and must fall in the range from 0 to 604800.

predictiveOffset

xs:int

An indicator of the offset in seconds from the current local time that defines a point in the future for which to obtain a traffic prediction tile. The permitted values are numeric-only, from 0 to 604800. The default value is -1, which provides a real-time traffic tile.

profile

xs:string

Profile defines such attributes as geographic coverage (TMC tables available for use).

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.

res

xs:string

An indicator of the map tile resolution to be used only with a quadkey tile address. It specifies the dimensions of a rendered square map tile in pixels. The permitted values are:

  • bitmap128
  • bitmap256
  • bitmap512
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.

zoom

xs:string

An indicator of the map zoom level. It dictates the visibility rules to be taken in account when selecting traffic data items. By default, if this parameter is not specified in a traffic flow data or traffic incident 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.

ts

xs:boolean

This parameter is used to provide the flow response with the traversable status information. This status informs about the state of the given traffic item. Where: When TS is set to "C", this is the standard road closure and the other attributes will be: SP="-1", SU="-1", JF="10.0". This is consistent with how TML Flow has always indicated closures since TML 2.0. When TS is set to "O", the road is open for traffic. This includes reversible roads that are open. When TS is set to "RNR" the reversible road is not routable and the other attributes will be: SP="-1", SU="-1", JF="-1".

Accepts the following values:

  • true
  • false

By default the value is set to false.

Addressing Schemes

Table 2. Addressing Schemes
Addressing Scheme Description
Quadkey A quadkey is a single value (expressed as a string) that identifies a map tile in a grid of tiles. See also Quadkeys.
Z/X/Y A group of three values that identify a map tile in a grid of tiles spanning the entire globe. The size of the grid depends on the map zoom level. The three values are:
  • Z = map zoom level
  • X = x coordinate of the tile in the grid at the zoom level indicated by Z
  • Y = y coordinate of the tile in the grid at the zoom level indicated by Z
See also The Mercator Projection.
Bounding Box An area defined by the geographic coordinates (latitude and longitude) of its top-left and bottom-right corners. The coordinates are specified in decimal degrees in compliance with WGS 84.
Proximity A circular area defined by the geographic coordinates of its center (latitude and longitude) and radius. The coordinates are specified in decimal degrees in compliance with WGS 84. The radius is given in meters.
Corridor An area defined by a path (a line that runs along its center) and width. The path is defined by a series of latitude/longitude pairs. The coordinates are specified in decimal degrees in compliance with WGS 84. The width is given in meters

Additional Resources

Table 3. Additional Request Parameters
Resource URL variable Description Example Response
version   Processes requests for version information for HERE Traffic API, including the components that make up the Traffic Service.
https://traffic.hereapi.cn/traffic/6.0/version
Service: Traffic Service, Version: 6.0.88.2
xsd incident.xsd Processes a request for the incidents XSD.
https://traffic.hereapi.cn/traffic/6.0/xsd/incident.xsd
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
XSD
xsd incident2.2.xsd Processes a request for the incidents version 2.2 XSD. This version is used with the /traffic/6.1/incidents endpoint
https://traffic.hereapi.cn/traffic/6.0/xsd/incidents2.2.xsd
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
XSD
xsd incident2.3.1.xsd Processes a request for the incidents version 2.3.1 XSD. This version is used with the /traffic/6.2/incidents endpoint
https://traffic.hereapi.cn/traffic/6.0/xsd/incidents2.3.1.xsd
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
XSD
xsd flow.xsd Processes a request for the XSD Schema used for the flow XSD (traffic flow with predictive data).
https://traffic.hereapi.cn/traffic/6.0/xsd/flow.xsd
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
XSD

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.

Response Data Format

This resource can deliver response data either in XML or JSON. To select the format use resource extensions .xml or .json, for example .../flow.json/..., .../incidents.xml/...

See also Examples for complete working URLs.

The following list summarizes the elements required to create a request matching the user story and shows, in square brackets, how those elements are used in the request example below. Note that the request example also uses the authentication parameters.

A spatial filter defines the area targeted by the request (the area for which to retrieve data or a map tile).