Traffic API Developer's Guide

Flow

This resource is responsible for servicing requests for traffic flow data for a geospatial area. The response contains speed and congestion ("jam factor") information. The delivery formats are either XML or JSON. A request can optionally specify shape and functional class information for the roadways for which to obtain traffic flow information.

Parameter Combinations for Common Use Cases

Table 1. Parameters for requesting Flow Data
Required Optional
  • quadkey, prox, bbox, or corridor (except with Z/X/Y address)
  • maxfunctionalclass
  • minjamfactor
  • maxjamfactor

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 2. Traffic Flow Request Parameters
Parameter Description
Authentification params
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, please 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, please see Acquiring Credentials.

Main (geospecial) filters
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.
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).

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.

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.

Additional filters
profile

xs:string

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

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 Requesting Traffic Flow Data with a 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

See Requesting Traffic Flow Data with DLR for an example request using the locationreferences parameter.

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

jsoncallback

xs:string

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

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.

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.

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.