Traffic API v6.0.67.1 Developer's Guide

Traffic API
Developer's Guide
Version 6.0.67.1
Traffic API Developer's Guide
► Notices
Important Information
Notices
Topics: This section contains document notices.
• Legal Notices
• Document Information
2
► Notices
Legal Notices
© 2017 HERE Global B.V. and its Affiliate(s). All rights reserved.
This material, including documentation and any related computer programs, is protected by copyright
controlled by HERE. All rights are reserved. Copying, including reproducing, storing, adapting or translating,
any or all of this material requires the prior written consent of HERE. This material also contains confidential
information, which may not be disclosed to others without the prior written consent of HERE.
Trademark Acknowledgements
HERE is trademark or registered trademark of HERE Global B.V.
Other product and company names mentioned herein may be trademarks or trade names of their respective
owners.
Disclaimer
This content is provided "as-is" and without warranties of any kind, either express or implied, including, but
not limited to, the implied warranties of merchantability, fitness for a particular purpose, satisfactory quality
and non-infringement. HERE does not warrant that the content is error free and HERE does not warrant or
make any representations regarding the quality, correctness, accuracy, or reliability of the content. You
should therefore verify any information contained in the content before acting on it.
To the furthest extent permitted by law, under no circumstances, including without limitation the negligence
of HERE, shall HERE be liable for any damages, including, without limitation, direct, special, indirect, punitive,
consequential, exemplary and/ or incidental damages that result from the use or application of this content,
even if HERE or an authorized representative has been advised of the possibility of such damages.
3
► Notices
Document Information

Product
Name: Traffic API
Version: Version 6.0.67.1

Document
Name: Traffic API Developer's Guide
ID: 2586d53-1507564449-7c116ff7
Status: FINAL
Date: 2017-Oct-09, 15:56 (GMT)

4
► Contents
Contents
Chapter 1: Introduction.................................................................................................................................................................. 7
What Is the Traffic API?................................................................................................................................................................................... 8
Why Use the Traffic API?................................................................................................................................................................................ 8
Chapter 2: Quick Start..................................................................................................................................................................... 9
Requesting Traffic Incident Data..............................................................................................................................................................10
Chapter 3: Guide................................................................................................................................................................................... 13
Key Concepts....................................................................................................................................................................................................... 14
The Mercator Projection............................................................................................................................................................................ 14
Quadkeys............................................................................................................................................................................................................ 15
Limitations.........................................................................................................................................................................................................16
Common Acronyms....................................................................................................................................................................................... 19
Acquiring Credentials...................................................................................................................................................................................... 21
Constructing a Request..................................................................................................................................................................................21
HERE Server Environments...................................................................................................................................................................... 22
Filtering TMC Tables........................................................................................................................................................................................ 22
Filtering Traffic Flow Data............................................................................................................................................................................ 23
Filtering Traffic Incident Data.................................................................................................................................................................... 23
Obtaining Traffic Tiles.................................................................................................................................................................................... 25
Selecting a Request Pattern....................................................................................................................................................................... 26
Examples................................................................................................................................................................................................................ 28
Traffic Flow Data........................................................................................................................................................................................... 29
Traffic Flow Data in a Specified Area............................................................................................................................................ 29
Bounding Box Filter................................................................................................................................................................................. 30
Traffic Flow Data with Max Functional Class Filter................................................................................................................. 31
Traffic Flow Data with DLR...................................................................................................................................................................32
Road Shape and Road Class Filters................................................................................................................................................ 33
Traffic Tiles....................................................................................................................................................................................................... 34
Traffic Flow Tile Overlays..................................................................................................................................................................... 35
Traffic Pattern Tile....................................................................................................................................................................................36
Selecting a Tile Size................................................................................................................................................................................. 37
5
► Contents
Selecting a Tile Color Depth............................................................................................................................................................... 38

Including a TMC Table............................................................................................................................................................................ 39
Excluding a TMC Table........................................................................................................................................................................... 39
Traffic Tiles with DLR.............................................................................................................................................................................. 40
Traffic Incident Data.................................................................................................................................................................................... 41
Localized Incident Data......................................................................................................................................................................... 41
Subset of Incident Data........................................................................................................................................................................ 44
Request Flow Availability.......................................................................................................................................................................... 47
Service Support................................................................................................................................................................................................. 48
Chapter 4: API Reference......................................................................................................................................................... 49
Resources.............................................................................................................................................................................................................. 50
Flow...................................................................................................................................................................................................................... 50
Tiles.......................................................................................................................................................................................................................53
Incidents............................................................................................................................................................................................................ 56
Incidents 6.2..................................................................................................................................................................................................... 61
Flowavailability...............................................................................................................................................................................................66
Meta Resources.............................................................................................................................................................................................. 67
Data Types............................................................................................................................................................................................................ 68
Latitude.............................................................................................................................................................................................................. 68
Longitude........................................................................................................................................................................................................... 69
Functional Class.............................................................................................................................................................................................69
TMC Code........................................................................................................................................................................................................... 69
Language Code............................................................................................................................................................................................... 70
Language Code Parameters.....................................................................................................................................................................70
Country Code................................................................................................................................................................................................... 70
Built-in................................................................................................................................................................................................................. 71
xs:dateTime....................................................................................................................................................................................................71
List ResourceTypes................................................................................................................................................................................... 72
Sequence of Same Resource Types Elements........................................................................................................................... 73
HTTP Status Codes........................................................................................................................................................................................... 74
HTTP Headers...................................................................................................................................................................................................... 75
Chapter 5: Coverage Information.................................................................................................................................. 76
Traffic Coverage..................................................................................................................................................................................................77
Supported Translation Languages...........................................................................................................................................................82
6
► Introduction
Chapter 1
Introduction
Topics: This document introduces the Traffic API and:
• What Is the Traffic API? • explains key concepts
• Why Use the Traffic API? • provides examples
• documents resources and query parameters
• documents response structures and data types
7
► Introduction
What Is the Traffic API?

The HERE Traffic API is a REST API that provides traffic flow and incidents information. This API also allows
you to request traffic map tiles that visualize the data available.
Why Use the Traffic API?

The Traffic API provides resources to address the following high-level use cases:
Table 1: Main features of the HERE Traffic API
Feature Description
Traffic Incident Data The API provides aggregated information about traffic incidents in XML or JSON, including
the type and location of each traffic incident, status, start and end time, and other
relevant data. This data is useful to dynamically optimize route calculations.
Traffic Map Tile Overlays (Traffic Tiles) The API delivers pre-rendered map tile overlays with traffic information that you can
readily display with your mapping application. You can request map tiles that show
traffic data for a specific area.
Traffic Flow Data The API provides access to real-time traffic flow data in XML or JSON, including
information on speed and congestion for the region(s) defined in each request. The API
can also deliver additional data such as the geometry of the road segments in relation to
the flow.
Traffic Flow Availability The API allows client applications to access traffic flow information (excluding incidents)
in an area, if available. The area is specified by a map segment (defined as a map view)
or for the whole world (without the map view).
8
► Quick Start
Chapter 2
Quick Start
Topics: This section illustrates how a basic request with the Traffic API
• Requesting Traffic Inciden... works.
9
► Quick Start
Requesting Traffic Incident Data

The following GET request obtains traffic incident data for an area around Frankfurt, Germany .
https://traffic.cit.api.here.com/traffic/6.2/incidents/xml/8/134/86
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
The response to the above request contains the following high-level elements:
• a timestamp of the obtained traffic data

• an array of <TRAFFIC_ITEM> elements that contain the incident location, time, duration, severity,
description and other details
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<TRAFFICML_INCIDENTS TIMESTAMP="03/17/2017 09:48:27" TIMESTAMP2="2017-03-17T09:48:27Z"
EXTENDED_COUNTRY_CODE="E0">
<TRAFFIC_ITEMS>
<TRAFFIC_ITEM mid="10831636_original">
<TRAFFIC_ITEM_ID>881739768227194517</TRAFFIC_ITEM_ID>
<ORIGINAL_TRAFFIC_ITEM_ID>3795526337806050757</ORIGINAL_TRAFFIC_ITEM_ID>
<TRAFFIC_ITEM_STATUS_SHORT_DESC>ACTIVE</TRAFFIC_ITEM_STATUS_SHORT_DESC>
<TRAFFIC_ITEM_TYPE_DESC>CONSTRUCTION</TRAFFIC_ITEM_TYPE_DESC>
<START_TIME>01/13/2017 09:03:03</START_TIME>
<END_TIME>12/31/2017 22:59:53</END_TIME>
<ENTRY_TIME>03/14/2017 17:04:00</ENTRY_TIME>
<CRITICALITY>
<ID>0</ID>
<DESCRIPTION>critical</DESCRIPTION>
</CRITICALITY>
<VERIFIED>true</VERIFIED>
<ABBREVIATION>
<SHORT_DESC>CONST</SHORT_DESC>
<DESCRIPTION>construction</DESCRIPTION>
</ABBREVIATION>
<COMMENTS>B26, Schweinfurt - Aschaffenburg in beiden Richtungen, zwischen
Anschlussstelle Hösbach und Anschlussstelle Goldbach, wegen Baustelle gesperrt, eine Umleitung ist
eingerichtet, bis 31.12.2017</COMMENTS>
<RDS-TMC_LOCATIONS>
<RDS-TMC>
<ORIGIN>
<EBU_COUNTRY_CODE>D</EBU_COUNTRY_CODE>
<TABLE_ID>1</TABLE_ID>
<LOCATION_ID>22235</LOCATION_ID>
<LOCATION_DESC>Laufach</LOCATION_DESC>
<RDS_DIRECTION>+</RDS_DIRECTION>
</ORIGIN>
<TO>
<LOCATION_DESC>Goldbach</LOCATION_DESC>
<RDS_DIRECTION>+</RDS_DIRECTION>
</TO>
<DIRECTION>-</DIRECTION>
<ALERTC>
<TRAFFIC_CODE>735</TRAFFIC_CODE>
<QUANTIFIERS>0</QUANTIFIERS>
<DESCRIPTION>Wegen Baustelle gesperrt.</DESCRIPTION>
<ALERTC_DURATION>L</ALERTC_DURATION>
10
► Quick Start
<ALERTC_DIRECTION>1</ALERTC_DIRECTION>
<URGENCY>U</URGENCY>
<UPDATE_CLASS>5</UPDATE_CLASS>
<PHRASE_CODE>E1.C1</PHRASE_CODE>
<EXTENT>1</EXTENT>
<DURATION>0</DURATION>
</ALERTC>
<PRIMARY_OFFSET>0.96933</PRIMARY_OFFSET>
<LENGTH>1.69523</LENGTH>
</RDS-TMC>
</RDS-TMC_LOCATIONS>
<LOCATION>
<DEFINED>
<ORIGIN>
<ROADWAY ID="50280">
<DESCRIPTION TYPE="NTCSA">B26</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">B26</DESCRIPTION>
<DESCRIPTION TYPE="LOCAL">B26</DESCRIPTION>
</ROADWAY>
<POINT ID="22235">
<DESCRIPTION TYPE="NTCSA">Laufach</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">Laufach</DESCRIPTION>
<DESCRIPTION TYPE="LOCAL">Laufach</DESCRIPTION>
<DESCRIPTION TYPE="BNAME">B26</DESCRIPTION>
</POINT>
<DIRECTION ID="0">
<DESCRIPTION TYPE="LOCAL">ASCHAFFENBURG</DESCRIPTION>
<DESCRIPTION TYPE="NTCSA">ASCHAFFENBURG</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">ASCHAFFENBURG</DESCRIPTION>
</DIRECTION>
<PROXIMITY>
<ID>AT</ID>
<DESCRIPTION>at</DESCRIPTION>
</PROXIMITY>
</ORIGIN>
<TO>
</ROADWAY>
<POINT ID="22234">
<DESCRIPTION TYPE="NTCSA">Goldbach</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">Goldbach</DESCRIPTION>
<DESCRIPTION TYPE="LOCAL">Goldbach</DESCRIPTION>
<DESCRIPTION TYPE="BNAME">B26</DESCRIPTION>
</POINT>
<DIRECTION ID="0">
<DESCRIPTION TYPE="LOCAL">ASCHAFFENBURG</DESCRIPTION>
<DESCRIPTION TYPE="NTCSA">ASCHAFFENBURG</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">ASCHAFFENBURG</DESCRIPTION>
</DIRECTION>
<PROXIMITY>
<ID>AT</ID>
</PROXIMITY>
</TO>
</DEFINED>
<GEOLOC>
<ORIGIN>
<LATITUDE>50.005303</LATITUDE>
<LONGITUDE>9.225782</LONGITUDE>
</ORIGIN>
<TO>
</TO>
11
► Quick Start
</GEOLOC>
<NAVTECH>
<EDGE>
<EDGE_ID>1063970961</EDGE_ID>
<EDGE_ID>...</EDGE_ID>
</EDGE>
<VERSION_ID>201701</VERSION_ID>
</NAVTECH>
</LOCATION>
<TRAFFIC_ITEM_DETAIL>
<ROAD_CLOSED>true</ROAD_CLOSED>
<EVENT>
<EVENT_ITEM_CANCELLED>false</EVENT_ITEM_CANCELLED>
<SCHEDULED_CONSTRUCTION_EVENT>
<SCHEDULED_CONSTRUCTION_TYPE_DESC>CONSTRUCTION</
SCHEDULED_CONSTRUCTION_TYPE_DESC>
<SCHEDULED_CONSTRUCTION_DETAIL>construction</SCHEDULED_CONSTRUCTION_DETAIL>
</SCHEDULED_CONSTRUCTION_EVENT>
</EVENT>
</TRAFFIC_ITEM_DETAIL>
<TRAFFIC_ITEM_DESCRIPTION TYPE="short_desc">Geschlossen zwischen Laufach und Goldbach -
Wegen Baustelle gesperrt. eine Umleitung ist eingerichtet.</TRAFFIC_ITEM_DESCRIPTION>
<TRAFFIC_ITEM_DESCRIPTION TYPE="desc">Geschlossen zwischen Laufach und Goldbach -
Wegen Baustelle gesperrt. eine Umleitung ist eingerichtet. B26, Schweinfurt - Aschaffenburg in
beiden Richtungen, zwischen Anschlussstelle Hösbach und Anschlussstelle Goldbach, wegen Baustelle
gesperrt, eine Umleitung ist eingerichtet, bis 31.12.2017</TRAFFIC_ITEM_DESCRIPTION>
<TRAFFIC_ITEM_DESCRIPTION TYPE="no_exit_description">Wegen Baustelle gesperrt. eine
Umleitung ist eingerichtet. B26, Schweinfurt - Aschaffenburg in beiden Richtungen, zwischen
Anschlussstelle Hösbach und Anschlussstelle Goldbach, wegen Baustelle gesperrt, eine Umleitung ist
eingerichtet, bis 31.12.2017</TRAFFIC_ITEM_DESCRIPTION>
</TRAFFIC_ITEM>
<TRAFFIC_ITEM mid="13510316">...
</TRAFFIC_ITEM>
...
</TRAFFIC_ITEMS>
</TRAFFICML_INCIDENTS>
Related Information
• Constructing a Request
• Filtering TMC Tables
• Filtering Traffic Incident Data
• Filtering Traffic Flow Data
• Incidents
• Key Concepts
• Obtaining Traffic Tiles
• Selecting a Request Pattern
12
► Guide
Chapter 3
Guide
Topics: This section examines aspects of the HERE Traffic API in detail,
• Key Concepts covering:
• Acquiring Credentials
• authentication credentials
• Filtering TMC Tables
• REST request formats and URL construction
• Filtering Traffic Flow Dat... • Traffic API Flow Data Service
• Filtering Traffic Incident... • rendered traffic flow tiles
• Obtaining Traffic Tiles
• incident data
• Selecting a Request Patter...
• Examples Further articles in this section offer examples that match various
• Service Support use cases for the API. You can use and modify the examples to
explore the API and build your own applications, provided that you
replace the demo authentication parameter values with your own
authentication credentials.
Deprecation Notice
HERE has changed the way traffic tiles are served. Live traffic tiles have been
deprecated in the Traffic API and are now delivered by the Map Tile API
infrastructure. Documentation on live traffic tiles is part of the Map Tile API
documentation.
This does not affect traffic pattern tiles, which continue to be served by the Traffic
API.
13
► Guide
Key Concepts
This section provides information intended to help you understand and use the Traffic API.
The Mercator Projection

The Traffic API serves map tiles obtained by mapping points on the surface of a sphere (the globe) to points
on a plane, using the normalized Mercator projection.
The basic Mercator projection formula is this:
{λ, φ} -> x[-1, 1] y [-1, 1]
In this formula:
λ = longitude
φ= latitude
x= λ/π
y = ln(tan(π/4 + φ/2)) / π
The plane represents the globe as a square grid of map tiles. The size of the grid depends on the map zoom
level. At the lowest zoom level, the world is contained in one map tile. At the next higher zoom level, the
world is two tiles wide and two tiles high (2x2), at the next level above that, the grid is 4x4, then 8x8, 16x16,
and so on up to the maximum zoom for a particular region. In other words, at each zoom level the tiles that
make up the complete map of the world form a grid in which the number of tiles is equal to two to the power
of two multiplied by the zoom level (2 ).
(2*zoom)
The relationship between tiles at two consecutive zoom levels can be expressed as follows:
col1,z+1 = (2*colz) + 1row1,z+1 = (2*rowz) + 1
In this formula:
col = column number in the tile

grid
row= row number in the tile grid
z = zoom level
14
► Guide
The diagram below demonstrates this graphically:
Figure 1: Tiles at different zoom levels
You can use this information to obtain the grid coordinates (row and column) of the map tile for a particular
geographic location in your application. The following pseudo code contains the complete algorithm:
--- javascript ---

var lat = 52.525439, // Latitude
lon = 13.38727, // Longitude
z = 12, // Zoom level
latRad,
n,
xTile,
yTile;
latRad = lat * Math.PI / 180;

n = Math.pow(2, z);
xTile = n * ((lon + 180) / 360);
yTile = n * (1-(Math.log(Math.tan(latRad) + 1/Math.cos(latRad)) /Math.PI)) / 2;
--- output ---

lat_rad = 0.916
n = 4096
xTile = 2200.31 // Column
yTile = 1343.20 // Row
The zoom level and tile row and column can be used as URL variables separated by the '/' character in
map tile requests. Note that they must be provided in this order: zoom/column/row. This is the [Z]/[X]/[Y]
addressing scheme.
The map tile specification is typically preceded by other path variables and may be followed either by further
path variables and/or query parameters.
Quadkeys
Specifying the grid location of a map tile in terms of zoom level, column and row as described under The
Mercator Projection on page 14 is easy to understand and intuitive in practise. However, the grid is a
two-dimensional array and as such does not offer efficient storage and retrieval. A better solution is a one-
dimensional array, where each item is uniquely addressable by a single value. This is made possible by
quadkeys, which combine the zoom level, column and row information for a tile in a one value.
15
► Guide
In fact, a quadkey is a string containing a numeric value. The value is obtained by interleaving the bits of
the row and column coordinates of a tile in the grid at the given zoom level, then converting the result to
a base-4 number (the leading zeros are retained). The length of a quadkey string (the number of digits/
characters) equals the zoom level of the tile.
For example, we can obtain the quadkey for a map tile in column 3 and row 5 at zoom level 5 as follows:
// Convert the column (x) and row (y) values

// to their binary (b) equivalents:
x = 3 -> 011b
y = 5 -> 101b
// Interleave the binary values (b), convert the

// combined result to a base-4 (q) number and
// finally convert that to a string:
quadkey = 100111b -> 213q -> "213"
The code below shows a JavaScript implementation of the algorithm that calculates quadkeys. The inputs are
the coordinates of the a map tile and the zoom level. The return value is a string containing the quadkey. The
lower part of the code block shows the function called to calculate a quadkey for zoom level 16, which is also
the length of the output string shown on the last line.
--- input ---

xTile: 35210 // Column
yTile: 21493 // Row
z: 16 // Zoom Level
--- JavaScript ---

function tileXYToQuadKey(xTile, yTile, z) {
var quadKey = "";
for (var i = z; i > 0; i--) {
var digit = "0",
mask = 1 << (i - 1);
if ((xTile & mask) != 0) {
digit++;
}
if ((yTile & mask) != 0) {

digit = digit + 2;
}
quadKey += digit;
} // for i return quadKey;
return quadKey;
}
quadKey = tileXYToQuadKey(35210, 21493, 16);
--- output ---

quadKey = "1202102332221212"
Note that when using a quadkey address, you cannot specify the size or format of the map tile image. The
response always includes an image that measures 256 x 256 pixels and the format is png32.
Limitations
To reduce the size and increase the relevance of traffic data, the Traffic API allows you to limit the area and
detail of traffic flow data, traffic tiles, and incident data that you can obtain via queries. In addition, you can
request tiles or incident reports for zoom levels 8 to 21 only.
16
► Guide
Traffic Flow Data Limitations

The API restricts the maximum size of a geographical filter used to retrieve traffic flow data. The following
limitations apply to requests that specify a bounding box and proximity filters:
• Maximum width and height of a bounding box: 2 degrees of longitude and latitude
• Maximum permitted proximity radius: 100km
• Maximum allowed corridor length: 500km
• Maximum allowed corridor width: 10km
Although requests that specify very large spatial filters do not result in an error response, the response
specifies a limited amount of data, as described above.
Note: The HERE Service Agreement applies for the following recommended ranges:
• Maximum size for a bounding box and a quadkey ( tile): 8-21
• Maximum radius in proximity-based queries
For details on the HERE Service License Agreement, see the relevant documentation.
Traffic Tiles and Zoom Level

To avoid overcrowding the display, the display of tiles have the following limitations:
• The traffic flow detail changes with the zoom level.

• At low zoom levels, map tiles show traffic flow information only for the highest-level functional road
classes. Traffic on minor roads become visible and more detailed as the zoom level increases.
For example:
• At zoom level 14, traffic information is displayed on highways
• At zoom level 15, traffic information is shown on highways and state roads
However, you may have access to a customized profile that displays different traffic flow data, depending on
the zoom level.
17
► Guide
The images below demonstrate traffic tile detail available at different zoom levels. The first two images
contain no traffic information, because the zoom level is at 5, which is too low. As the zoom level increases in
further tiles, traffic flow data on increasingly lower functional road classes become visible.
Figure 2: Zoom level too low to show traffic
In the image below, zoom level 8 shows some traffic flow information.
Figure 3: Zoom level 8 begins to show traffic flow overlay
18
► Guide
The higher the zoom level, the more detailed the traffic flow display becomes:
Figure 4: Zoom level 14 shows more detailed traffic flow overlay
Traffic Incident and Zoom Level

Similar to the limitation of traffic flow data, the Traffic API has limitations on traffic incident information
which prevent large response data transfers that are unsustainable:
• No display of traffic incident information: zoom levels 0-7

• Maximum bounding box width and height: 30 degrees of latitude and longitude
• Maximum permitted size of the proximity radius: 100km
• Maximum allowed corridor length: 500km
Note: Queries exceeding the limits in terms of zoom level or proximity radius result in an error
response.
Common Acronyms
The table below lists the common acronyms used throughout this document and their meaning.
Table 2: Acronyms and Definitions
Acronym Definition
CF The Current Flow for the location. Current Flow is comprised of several attributes that
describe how traffic is moving at location.
19
► Guide
Acronym Definition
CN The Confidence attribute, which is a number between 0.0 and 1.0 indicating the
percentage of real time data included in the speed calculation.
• A value greater than 0.7 and less than or equal to 1.0 indicates real time speeds
• A value greater than 0.5 and less than or eqaul to 0.7 indicates historical speeds
• A value greater than 0.0 and less than or equal to 0.5 indicates speed limit
• A value of -1.0 indicates road closed or unable to calculate
To only report speeds where real time data is available, we recommend that you include
speeds with a confidence greater than 0.7 CN and include road closures with a value =
-1.0 CN
FI The entry for each Flow Item in the specified direction.
FIS A list of Flow Items (FI), one list for each direction of the roadway(RW). (1-many)
The FI in each FIS section is guaranteed to be contiguous and in the order of the
driving direction. If there is a break in continuity on an RW, then there are 2 or more FIS
elements in the RW.
JF A number between 0.0 and 10.0 indicating the Jam Factor, which represents the expected
quality of travel. When there is a road closure, the Jam Factor is 10.
However, a reversible not routable status uses a Jam Factor of -1 as most applications do
not want to display a blackout as a closure on the map. As the number approaches 10.0,
the quality of travel degrades. -1.0 indicates that a Jam Factor could not be calculated.
TS The Traversable Status (TS) can be set to C for Closed, O for Open, and RNR for Reversible
not routable. When TS is set to C, this is the standard road closure and the other
attributes are then set to: 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 are
then set to: SP=-1, SU=-1, JF=-1. The application can deal with reversible not routable in
any way, but it is recommended that it is used to indicate not routable and to not show
traffic on this roadway in the map display. This is the best source of information when
routing through reversible lanes. This data is more accurate than any source, including
HERE Maps, as published reversible information can be changed based on daily traffic
flow or special events. For reversible roads, both full linears are not routable for portions
of the day when the road direction is being switched. There is a possibility that portions
of a reversible road are marked as Closed rather than RNR; when this happens, both
directions of the reversible are closed, which can happen for construction or major
accidents.
SU A number that indicates the average Speed Uncut (SU) for the road segment. Uncut
means that the speed limit for the road segment is ignored. Speeds that are over the
speed limit are included in the average.
SP A number that indicates the average Speed (SP) for the road segment. The average does
not take speeds that are over the speed limit into account. Speeds that are over the
speed limit are trimmed down to the speed limit.
QD This data type indicates the Queuing direction (QD) of the traffic. When traffic becomes
congested, a queue of vehicles begins to build up in the opposite direction to the driving
direction. The value an be "+" or "-". The value "-" indicates that the traffic is queued in
the opposited direction to the driving direction.
20
► Guide
Acquiring Credentials
All users of HERE APIs must obtain authentication and authorization credentials and provide them as values
for the parameters app_id and app_code. The credentials are assigned per application.
This document uses the placeholder text {YOUR_APP_ID} and {YOUR_APP_CODE} as placeholders for
access and authorization credentials. Replace these placeholders with your own unique application-specific
credentials to access the API resources.
To obtain the credentials for an application, please visit http://developer.here.com/plans to register with
HERE.
If you wish to explore the API, use the API Explorer at https://developer.here.com/api-explorer.
Constructing a Request
A typical request to the Traffic API includes the basic elements shown in the following table and may contain
resource-specific parameters or data
Table 3: Basic request elements
Element Value/Example Purpose Description/comments
Base URL https://tiles.traffic.api.here.com Tiles Production environment.
https://traffic.api.here.com Incidents, Flow, or Flow

Availability
https://tiles.traffic.cit.api.here.com Tiles CIT environment
https://traffic.cit.api.here.com Incidents, Flow, or Flow For more information

Availability about the available
environments, see HERE
Server Environments
Path /traffic/6.0/ For tiles and

flowavailability resources
/traffic/6.2/ For incidents resource
/traffic/6.2/ For flow resource
Resource tiles To obtain traffic map tiles Name of a resource.
Only the GET method is

incidents To obtain traffic incident data
supported. Parameters
flow To obtain traffic flow data specify request details.
See also Examples on page
28.
flowavailability To obtain information on traffic
flow availability
21
► Guide
Element Value/Example Purpose Description/comments
Addressing Quadkey, [Z]/[X]/[Y], Bounding Box, Corridor or Traffic Flow Data Geographic area for which
Scheme Proximity to retrieve data; options
depend on resource/
Quadkey, [Z]/[X]/[Y] Traffic Tiles function.
Quadkey, [Z]/[X]/[Y], Bounding Box, Corridor or Traffic Incidents

Proximity
Customer Profile or Mapview Traffic Flow Availability
Application &app_code={YOUR_APP_CODE} All requests Substitute your own

Code unique app_code.
Application Id &app_id={YOUR_APP_ID} All requests Substitute your own

unique app_id.
For further information, see Examples.
HERE Server Environments

HERE provides two server environments for handling your requests: a Production environment and a
Customer Integration Testing (CIT) environment.
You are required to use the CIT Environment when evaluating our products via our 90-day free trial.
To access CIT for REST APIs, amend the base URL to include an additional cit segment. For example, the CIT
URL for this API is https://traffic.cit.api.here.com.
HERE examples and demos use this CIT environment only to provide an illustration of how the service
operates.
You are required to use the Production environment for general production use. The CIT environment must
not be used for production.
High Loads and Performance Testing

Neither standard server environment (CIT and Production) is designed to support high loads or performance
testing. You must not conduct performance tests against the CIT or Production environments. If you need to
do performance testing, contact HERE to discuss options.
Filtering TMC Tables

A customer profile includes a set of TMC tables, that specify the traffic data that you can request from the
service. Requests that use TMC tables follow the same pattern as requests for traffic flow tile overlays, but
differ in terms of parameters.
For a list of sample TMC codes, see Traffic Coverage .
You can include or exclude certain tables in your profile via the tables parameter in the request, paired
with the TMC code. Positive values for the TMC code specify the tables to include; negative values specify the
22
► Guide
tables to exclude. You cannot combine a positive and negative value in a request as such a request is not
supported and results in an error.
Related Information
• Including a TMC Table
• Excluding a TMC Table
• Requesting Traffic Tiles with DLR
• TMCCodeType
Filtering Traffic Flow Data

You can use the flow resource to request traffic flow data containing speed and congestion ("jam factor")
information for a geospatial area. The response data format is either XML or JSON. Optionally, your request
can specify shape and functional class information to further identify the roadways for which you wish to
obtain traffic flow information.
Geospatial Inclusion
The service supports the following geospatial filters (addressing schemes):
• quadkey
• [Z]/[X]/[Y]
• bounding box (bbox)
• proximity (prox)
• corridor
For more information about these filters, see Selecting a Request Pattern on page 26.
Note: Response only include subcomponents of roadway items (RW) that fall within the geospatial
address.
Content Filters
By default, a response contains all the available flow information for the specified spatial filter. It is,
however, possible to add a further filter based on the functional class of the road through the parameter
maxfunctionalclass, and a filter for minimum and maximum jam factor values through the parameters
minjamfactor and maxjamfactor.
Filtering Traffic Incident Data

The HERE Traffic API supports requests for traffic incident data from a specific geographic area (defined by a
geospatial filter). The response includes data in XML or JSON format.
23
► Guide
Geospatial Inclusion
A response includes traffic incident items based on their point of origin. So an incident in the response may potentially
contain a geolocation outside the area indicated by the geospatial filter in the request. The code example below shows the
GEOLOC/ORIGIN parameter used to determine if an item falls within the requested response boundaries.
...
<GEOLOC>
<ORIGIN>
<LONGITUDE>-122.38732</LONGITUDE>
</ORIGIN>
<TO>
<LONGITUDE>-122.3657107</LONGITUDE>
</TO>
</GEOLOC>
...
Incident Types and Filtering

Incident filters allow you to tailor incident requests to specific requirements. The filters support selection
based on status, criticality, TMC table IDs, profiles, or start and end times.
In addition, traffic incidents are classified according to incident type:

• Accident
• Congestion
• Construction
• Disabled vehicle
• Mass transit
• Miscellaneous
• Other news
• Planned event
• Road hazard
• Weather
Localization Defaults
By default, incident reports included in the response are localized based on their geographic origin. This
means the time values are shown in local time and format, and message strings are in the default language
for the country identified by the geospatial filter.
The table below shows the default languages for each supported country.
Table 4: Default Traffic Incident Reports Language
Country Default Incident Reports Language
Austria German (de)
Belgium Dutch (nl)
Canada English (en)
Denmark Danish (da)
Finland Finnish (fi)
24
► Guide
Country Default Incident Reports Language
France French (fr)
Germany German (de)
Greece Greek (el)
Ireland English (en)
Italy Italian (it)
Luxembourg French (fr)
Mexico Spanish (es)
Netherlands Dutch (nl)
Norway Norwegian (no)
Poland Polish (pl)
Portugal Portuguese (pt)
Russia Russian (ru)
South Africa English (en)
Sweden Swedish (sv)
Switzerland German (de)
Turkey Turkish (tr)
UK English (en)
USA English (en)
Supported Translation Languages

For the list of supported languages for incidents, see Supported Translation Languages.
Obtaining Traffic Tiles

The Traffic API allows you to obtain pre-rendered map tiles that reflect traffic conditions. Each tile is a PNG
overlay that uses lines and colors to indicate how freely traffic flows in the corresponding geographic area.
Deprecation Notice
HERE has changed the way traffic tiles are served. Live traffic tiles have been deprecated in the Traffic API and are now delivered by
the Map Tile API infrastructure. Documentation on live traffic tiles is part of the Map Tile API documentation.
This does not affect traffic pattern tiles, which continue to be served by the Traffic API.
Color Mapping
By default, the service uses specific color mappings that match a traffic scale measured in Jam Factors, where
0 means "free flowing" and 10 means "completely obstructed". The following table describes the overlay
colors, which follow a standard configuration to map Jam Factors to color.
25
► Guide
Table 5: Traffic Flow to Color Mapping
Color Description
Green Free flow of traffic: 0 <= JAM_FACTOR < 4
Yellow Sluggish flow of traffic: 4 <= JAM_FACTOR < 8
Red Slow flow of traffic: 8 <= JAM_FACTOR < 10
Black Traffic stopped flowing or road closed: JAM_FACTOR = 10
You can define customized profiles that specify different colors for the traffic flow statuses
Caching
Traffic flow tiles can be cached for a limited period of time (up to three minutes), as the data must be fresh
to represent the current traffic conditions reliably.
Selecting a Request Pattern

Each request must conform to the format appropriate to the resource (service function) and the addressing
scheme (geospatial filter) the request uses to define the area for which to retrieve traffic information.
The supported addressing schemes are:
• Tile addressing schemes:
▫ [Z]/[X]/[Y] – specifies the map zoom level and the coordinates of the map tile in the tile grid
corresponding to that zoom level, see The Mercator Projection on page 14 for details
▫ quadkey – an alternative to the [Z]/[X]/[Y] addressing scheme that uses a single value to identify the
map tile, see also Quadkeys on page 15
• Area filters:
▫ bounding box – defines the area for which to retrieve information as a bounding box (using the
parameter bbox, whose value is specified as the latitude and longitude of the top left and bottom
right corners of the area, for example, bbox=52.516,13.355;52.511,13.400)
▫ proximity – defines the area for which to retrieve information as a circle (using the parameter prox,
whose value is the latitude and longitude of the search center, followed by the radius of the search
area in meters)
▫ corridor – defines the area for which to retrieve information along a specified path (using the
parameter corridor, with 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.)
For information about addressing schemes and available resources, see Table 3: Basic request elements on
page 21.
Once you have determined the resource and the addressing scheme, select the appropriate request format
pattern, following the guidelines below (listed according to the API resource, whose name is shown in
brackets).
26
► Guide
Traffic Flow Data (flow)

You can obtain a traffic flow using one of the following request patterns, which reflect the addressing
scheme:
Table 6: Traffic Flow Data Request Patterns
Addressing scheme URL pattern
[Z]/[X]/[Y] {base-url}/{path}/{resource}/{format}/{zoom}/{column}/{row}?
Quadkey {base-url}/{path}/{resource}.{format}?quadkey={quadkey}
Bounding box {base-url}/{path}/{resource}.{format}?bbox={bounding box coordinates}
Proximity {base-url}/{path}/{resource}.{format}?prox={proximity coordinates}
Corridor {base-url}/{path}/{resource}.{format}?corridor={corridor coordinates}
Note: In the request patterns above, {path} must be /traffic/6.2/ .
Traffic Incidents (incidents)

You can obtain traffic incident reports using one of the following request patterns which reflect
the addressing scheme (this applies for both incident endpoints traffic/6.0/incidents and
traffic/6.1/incidents):
Table 7: Traffic Incident Request Patterns
Corridor coordinates {base-url}/{path}/{resource}.{format}?corridor={corridor coordinates}
Traffic Tile (tiles)

You can obtain traffic tiles using one of the following request patterns which reflect the addressing scheme:
Table 8: Traffic Tile Request Patterns
Addressing Scheme URL Pattern
[Z]/[X]/[Y] {tile-base-url}/{path}/{resource}/{format}/{resource}/{zoom}/{column}/{row}/
{size}?
Quadkey {tile-base-url}/{path}/{resource}/quadkeytraffic?quadkey={quadkey}
Note: When using the [Z]/[X]/[Y] tile addressing scheme, you can specify tile size and color depth as
follows:
• {size}: tile size, can be one the following values 512, 256, or 128.
• {format}: color-depth, can be one of the following png, png8, or png32.
27
► Guide
For more information, see Selecting a Tile Size on page 37 and Selecting a Tile Color Depth on page
38.
Traffic Flow Availability (flowavailability)

Traffic flow availability information can be retrieved for your profile with an address following the pattern
shown below:
Table 9: Traffic flow availability request pattern
Profile {base-url}/{path}/{resource}.{format}?profile={profile name}
Examples
This section provides examples of requests reflecting typical use cases for the Traffic API, along with the
corresponding results.
For readability, in some responses, line breaks are used and long strings are shortened with ellipsis (...).
The following example demonstrates search request for a traffic incident. The request uses bounding box
coordinates to define the area to search. The request uses the HTTP GET method and sets the bounding box
coordinates with a bbox. The value of the parameter is the latitude and longitude of the top left and bottom
right corners of the area for which to retrieve traffic incident data. The last parameter, criticality,
indicates the severity of the accidents about which to obtain information.
https://traffic.cit.api.here.com/traffic/6.2/incidents.json
&bbox=52.516,13.355;52.511,13.400
&criticality=minor
Where a request uses the Mercator Projection addressing scheme in the examples, it is possible to use the
Quadkey addressing scheme instead, or vice versa. For example, the following request using the Mercator
Projection addressing scheme and specifying JSON as the desired response format:
https://traffic.cit.api.here.com/traffic/6.2/flow/json/8/134/86
looks as follows when using the Quadkey addressing scheme instead, with the XML response format
specified:
https://traffic.cit.api.here.com/traffic/6.2/flow.xml
?quadkey=12020330
&app_id={YOUR_APP_ID}
Other ways to specify a location are to use the query parameters proximity (prox) or a bounding box filter
(bbox). For more information, see Limitations and Selecting a Request Pattern.
The response structure is based on the TML Formal Specification. For more information on TML, contact
Technical Customer Support.
28
► Guide
Traffic Flow Data

The examples listed below illustrate the common use cases for requesting traffic flow information from the
Traffic API in TrafficML Flow format version 3.2, available via the /traffic/6.2/ endpoint.
The following general request patterns are supported:
Table 10: Traffic Flow Data Request Patterns
Corridor {base-url}/{path}/{resource}.{format}?corridor={corridor coordinates}
For more information on TrafficML Flow, contact Technical Customer Support at tcs@here.com.
Traffic Flow Data in a Specified Area

The user wants to obtain traffic flow data for an area around Frankfurt am Main, Germany.
All requests for traffic flow data must address the flow resource and indicate the area for which to obtain
data.
Request
A request matching the user story is formulated as follows:
https://traffic.cit.api.here.com/traffic/6.2/flow/xml/8/134/86
To specify the tile for which to obtain traffic flow data, the request indicates the zoom level as 8, the tile
column as 134, and row as 86.
Response
The response carries the following XML contents:
<?xml version="1.0" encoding="UTF-8"?>

<TRAFFICML_REALTIME CREATED_TIMESTAMP="2017-06-01T14:04:43Z" MAP_VERSION="" UNITS="metric"
VERSION="3.2" xmlns="http://traffic.nokia.com/trafficml-flow-3.2">
<RWS EBU_COUNTRY_CODE="D" EXTENDED_COUNTRY_CODE="E0" MAP_VERSION="201702" TABLE_ID="1" TY="TMC"
UNITS="metric">
<RW DE="L3133" LI="D01-06664" PBT="2017-06-01T14:04:33Z" mid="7f81e8c6-da47-46fc-83ae-
a91f66ca2142|">
<FIS>
<FI>
<TMC DE="Pohlheim-Dorf-Güll" LE="0.97071" PC="6671" QD="+"/>
<CF CN="0.7" FF="35.0" JF="0.85714" SP="32.0" SU="32.0" TY="TR"/>
</FI>
29
► Guide
<FI>
<TMC DE="Pohlheim-Holzheim" LE="3.44059" PC="6670" QD="+"/>
</FI>
<FI>
<TMC DE="Langgöns" LE="4.87351" PC="6669" QD="+"/>
</FI>

</FIS>
</RW>
</RWS>
</TRAFFICML_REALTIME>
Related Information
• Parameters of the flow Resource
• Mercator Projection
• Quadkeys
Bounding Box Filter

The user wants to obtain traffic flow data for an area near Indianapolis, IN, USA. The area is a rectangle
defined by the latitude and longitude of its top-left and bottom-right corners.
Request
The query parameter bbox defines the latitudes and longitudes of the top left and bottom right corners of
the bounding box. The optional query parameter responseattributes requests that the response include
additional information on the shape and the functional class of the roadway corresponding to the flow items.
&bbox=39.8485715,-86.0969867;39.8358934,-86.0757964
&responseattributes=sh,fc
Note: For information about how to apply filters on the response to exclude flow information for
roads matching a particular functional class, see Traffic Flow Data with Max Functional Class Filter on
page 31.
Response
The response to the request contains:
• FI: traffic flow item with flow information about the area specified in the response and the related
current flow, including details about the shape and the functional class of the related roadway
Note: The response uses TMC references to provide the flow information.

<TRAFFICML_REALTIME CREATED_TIMESTAMP="2017-06-02T18:10:48Z" MAP_VERSION="" UNITS="imperial"
30
► Guide
<RWS EBU_COUNTRY_CODE="1" EXTENDED_COUNTRY_CODE="A0" MAP_VERSION="201702" TABLE_ID="7" TY="TMC"

UNITS="imperial">
<RW DE="Binford Blvd" LI="107+01100" PBT="2017-06-02T18:10:13Z" mid="1fe417f0-f17e-47b8-b0b0-
b67a71eec11d|">
<FIS>
<FI>
<TMC DE="E Kessler Boulevard East Dr" LE="1.5983" PC="8367" QD="-"/>
<SHP FC="3">39.8405,-86.11263 39.84072,-86.11237</SHP>
<SHP FC="3">39.84072,-86.11237 39.8413,-86.11168</SHP>
<SHP FC="3">39.8413,-86.11168 39.84181,-86.11106 39.84235,-86.11039 39.84307,-86.10953
39.84487,-86.10738 39.84663,-86.10527 39.84747,-86.10427 39.84793,-86.10369</SHP>
<SHP FC="3">39.84793,-86.10369 39.84886,-86.10255 39.84949,-86.10172 39.85041,-86.10046
39.85088,-86.09985 39.85137,-86.09926 39.85169,-86.09888 39.85203,-86.09854 39.85237,-86.09821
39.85272,-86.09789 39.85307,-86.09758 39.85343,-86.09729 39.8542,-86.09673 39.85502,-86.09616</SHP>
<SHP FC="3">39.85502,-86.09616 39.85534,-86.09595 39.85631,-86.09528 39.85691,-86.09487
39.85751,-86.09443</SHP>
<SHP FC="3">39.85751,-86.09443 39.85808,-86.09399 39.85836,-86.09379</SHP>
</FI>

</FIS>
</RW>
</RWS>
Related Information
• Quadkeys
Traffic Flow Data with Max Functional Class Filter

The user wants to obtain traffic flow data for an area around Frankfurt am Main, Germany. The area is
identified using the [Z]/[X]/[Y] addressing scheme, with map zoom level 9. The response includes data in XML
format, filtered to only include functional road class types no higher than 2.
Request
The [Z]/[X]/[Y] values are 9, 268, and 173 respectively. The maxfunctionalclass parameter is 2.
https://traffic.cit.api.here.com/traffic/6.2/flow/xml/9/268/173
?app_code={YOUR_APP_CODE}
&maxfunctionalclass=2
Response
The following code block shows the response the request for traffic flow data with a maximum functional
class filter. Note that this response is abbreviated because of space limitations. In reality, the XML may
contain a very large number of <RW> elements.

31
► Guide
<RWS EBU_COUNTRY_CODE="D" EXTENDED_COUNTRY_CODE="E0" MAP_VERSION="201702" TABLE_ID="1" TY="TMC"

UNITS="metric">
<RW DE="Frankfurter Straße" LI="D01-06899" PBT="2017-06-02T17:55:01Z" mid="8a7008fa-91c7-4e5d-
ab82-9fbd9e346e7b|">
<FIS>
<FI>
<TMC DE="Groß-Gerau" LE="0.39216" PC="6901" QD="+"/>
</FI>
</FIS>
</RW>
<RW DE="Frankfurter Straße" LI="D01+06899" PBT="2017-06-02T17:55:14Z" mid="31d22403-1827-4f5e-
aa95-ded5148e14d0|">
<FIS>
<FI>
<TMC DE="Groß-Gerau" LE="1.26399" PC="6901" QD="-"/>
</FI>
</FIS>
</RW>
</RWS>
Related Information
• Quadkeys
• maxfunctionalclass
Traffic Flow Data with DLR

The user wants to obtain traffic flow data with a Dynamic Location Reference (DLR), around Alexanderplatz,
Berlin.
Request
The query parameter bbox defines the latitudes and longitudes of the top left and bottom right corners of
the bounding box. The optional query parameter responseattributes requests that the response include
additional information on the shape of the roadway corresponding to the flow items
&bbox=52.5233,13.4035;52.5181,13.4159
&locationreferences=shp
Note: Typically, DLRs appear in arbitrary places, depending on traffic conditions. Sometime responses
to requests do not include any DLRs.
Response
32
► Guide
• <SHP> element for the shape which includes the FC attribute for the functional class information

<RWS EBU_COUNTRY_CODE="D" EXTENDED_COUNTRY_CODE="E0" MAP_VERSION="201702" TABLE_ID="1" TY="SHP"
UNITS="metric">
<RW PBT="2017-06-02T18:04:27Z" mid="c60928a9-61d2-45b7-bc41-8e0c9704a7cc~779602169N">
<FIS>
<FI>
<SHP FC="4" FW="SD" LE="0.06078" LID="779602169T">52.51483,13.39008 52.51477,13.38919</SHP>
</FI>
</FIS>
</RW>
<RW PBT="2017-06-02T18:08:34Z" mid="d2269eae-5fa5-447d-97c8-d3139db0ef92~923839888P">
<FIS>
<FI>
<SHP FC="4" FW="SD" LE="0.10319" LID="923839888F">52.4788,13.43603 52.47898,13.43752</SHP>
</FI>
</FIS>
</RW>
<RW PBT="2017-06-02T18:08:26Z" mid="4a85b6e8-21c4-463f-ae66-89b99b620e9d~53473556P">
<FIS>
<FI>
<SHP FC="5" FW="SD" LE="0.17662" LID="53473556F">52.49518,13.38403 52.49673,13.38459</SHP>
</FI>
</FIS>
</RW>
</RWS>
Related Information
• Flow Resource
• Quadkeys
Road Shape and Road Class Filters

The user wants to obtain the shape and functional class information of a roadway corresponding to the
specified flow item.
Request
The request specifies a bounding box area and uses the responseattributes parameter for the shape
and functional class information:
&bbox=39.8485715,-86.0969867;39.8358934,-86.0757964
&responseattributes=sh,fc
33
► Guide
Response
• FC attribute for the functional class information

• <SHP> element for the shape
Note: Response could be different depending on the endpoint used: for 6.1 endpoint <SHP> elements
for Ramps are not returned, for 6.2 endpoint all <SHP> are always returned.

<TRAFFICML_REALTIME CREATED_TIMESTAMP="2017-06-02T18:10:48Z" MAP_VERSION="" UNITS="imperial"
<RWS EBU_COUNTRY_CODE="1" EXTENDED_COUNTRY_CODE="A0" MAP_VERSION="201702" TABLE_ID="7" TY="TMC"
UNITS="imperial">
<RW DE="Binford Blvd" LI="107+01100" PBT="2017-06-02T18:10:13Z" mid="1fe417f0-f17e-47b8-b0b0-
b67a71eec11d|">
<FIS>
<FI>
<TMC DE="E Kessler Boulevard East Dr" LE="1.5983" PC="8367" QD="-"/>
<SHP FC="3">39.8405,-86.11263 39.84072,-86.11237</SHP>
<SHP FC="3">39.84072,-86.11237 39.8413,-86.11168</SHP>
<SHP FC="3">39.8413,-86.11168 39.84181,-86.11106 39.84235,-86.11039 39.84307,-86.10953
39.84487,-86.10738 39.84663,-86.10527 39.84747,-86.10427 39.84793,-86.10369</SHP>
<SHP FC="3">39.84793,-86.10369 39.84886,-86.10255 39.84949,-86.10172 39.85041,-86.10046
39.85088,-86.09985 39.85137,-86.09926 39.85169,-86.09888 39.85203,-86.09854 39.85237,-86.09821
39.85272,-86.09789 39.85307,-86.09758 39.85343,-86.09729 39.8542,-86.09673 39.85502,-86.09616</SHP>
<SHP FC="3">39.85502,-86.09616 39.85534,-86.09595 39.85631,-86.09528 39.85691,-86.09487
39.85751,-86.09443</SHP>
<SHP FC="3">39.85751,-86.09443 39.85808,-86.09399 39.85836,-86.09379</SHP>
</FI>

</FIS>
</RW>
</RWS>
Related Information
• Quadkeys
Traffic Tiles
This section offers examples of requests for traffic tile overlays from the Traffic API.
Deprecation Notice
The following general request patterns are supported:
34
► Guide
Table 11: Traffic Tile Request Patterns
Addressing Scheme URL Pattern
[Z]/[X]/[Y] {tile-base-url}/{path}/{resource}/{format}/{resource}/{zoom}/{column}/{row}/
{size}?
Quadkey {tile-base-url}/{path}/{resource}/quadkeytraffic?quadkey={quadkey}
Traffic Flow Tile Overlays

The user wants to obtain a traffic flow tile overlay for an area near Frankfurt, Germany. The area is identified
using the [Z]/[X]/[Y] addressing scheme. The resulting tile can be used to provide a visual indication of the
traffic conditions on the map.
Request
The [Z]/[X]/[Y] values are 8, 134, and 86 respectively. The resolution (size) is 256x256 pixels and the format
is png32.
https://tiles.traffic.cit.api.here.com/traffic/6.0/tiles/8/134/86/256/png32
Response
The response to the requests for a tile overlay for an area near Frankfurt in Germany contains the following
PNG traffic flow tile overlay image:
Figure 5: Traffic Flow Tile
Related Information
• Tiles
35
► Guide
Traffic Pattern Tile

The user wants to obtain a map tile showing a traffic pattern for a specific point of time, 5:40 PM, using the
quadkey addressing scheme.
Request
The point of time is specified as a number of seconds from the beginning of the week (00:00 hours, Sunday,
in local time. In this case, pattern_time = 150000. The quadkey value is 12020330.
https://tiles.traffic.cit.api.here.com/traffic/6.0/tiles/quadkeytraffic
&quadkey=12020330
&pattern_time=150000
Response
The response to the request for a traffic pattern tile overlay delivers the following PNG image:
Figure 6: Traffic Pattern Tile
If you remove the pattern_time parameter from the request, the response is a flow tile instead.
Figure 7: Flow Tile
Related Information
• Tiles
36
► Guide
Selecting a Tile Size

The user wants to obtain a traffic tile for an area near Frankfurt Germany, using the [Z]/[X]/[Y] addressing
scheme.
The request follows the same pattern as requests for traffic flow tile overlays, but requires the res
parameter to select the tile size and/or depth to determine the required color depth.
Request
The [Z]/[X]/[Y] values are 8, 134, and 86 respectively. The resolution (size) is 512x512 pixels and the format
is png32. Alternatively, you can also specify a resolution of 256x256 pixels or 128x128 pixels.
Response
The image below shows the tile delivered in response to the request.
Figure 8: Resized Large Flow Tile Request
Related Information
• Tiles
37
► Guide
Selecting a Tile Color Depth

The user wants to obtain a traffic tile, using the quadkey addressing scheme. The color depth of the tile
delivered by the response is to be 8 bits.
The request follows the same pattern as requests for traffic flow tile overlays, but requires the res
parameter to select the tile size and/or depth to determine the required color depth.
Request
The quadkey value is 12020330 and the depth is 8bit.
&quadkey=12020330
&depth=8bit
Response
The response to the request that stipulates the tile color depth delivers the tile shown below.
Figure 9: Flow Tile Request as 8-bit
Related Information
• Tiles
38
► Guide
Including a TMC Table

The user wants to obtain a traffic tile for an area near Boston, Massachusetts, on the border of TMC table
A0129. The request is to use the [Z]/[X]/[Y] addressing scheme and filter by the TMC table.
Request
The [Z]/[X]/[Y] values are 11, 613, and 759 respectively. The resolution (size) is 256x256 pixels, the format is
png32, and the tables value is A0129.
&tables=A0129
Response
The response contains a PNG traffic flow tile overlay, as shown below.
Figure 10: Request Including Table A0129
Related Information
• Tiles
Excluding a TMC Table

The user wants to obtain a traffic tile for an area near Boston, Massachusetts, on the border of TMC table
A0129. The request is to use quadkey addressing scheme and exclude the TMC table.
Request
The quadkey value is 03023320323 and the tables value is -A0129.
39
► Guide
&quadkey=03023320323
&tables=-A0129
Response
The response is a PNG traffic flow tile overlay, as shown below.
Figure 11: Request Excluding Table A0129
Related Information
• Tiles
Traffic Tiles with DLR

The user wants to obtain traffic tiles with a Dynamic Location Reference (DLR) around a location in Berlin.
Since a road in that area is not TMC-coded, DLR location referencing will be used to provide the required
traffic information.
Request
The code block below demonstrates a request that returns only DLR information:
?&app_id={YOUR_APP_ID}
&quadkey=120210233222203102
&locationreferences=shp
Response
The response is a PNG traffic flow tile overlay, as shown below.
40
► Guide
DLRs appear in arbitrary places depending on traffic conditions. It is possible that the request may not
return any DLRs. For this example, the response tile is in PNG format. DLRs are only used for small parts of
roads, hence the response image only covers those parts.
Figure 12: Request Traffic Tiles with DLR
Related Information
• Tiles
• Quadkeys
Traffic Incident Data

For a simple example of how to request traffic incident data, see Quick Start on page 9. This section contains
examples that illustrate further common use cases for requesting traffic incident data from the Traffic API.
The Traffic API supports the following general request patterns with traffic incident data requests:
Table 12: Traffic Incident Request Patterns
Corridor coordinates {base-url}/{path}/{resource}.{format}?corridor={corridor coordinates}
Localized Incident Data

The user wants to obtain traffic incident information for a tile at zoom level 8 representing an area near
Frankfurt, Germany. Instead of using the default settings for incident time zone, date format and language,
the intention is to localize the response to USA and include an English language version of the text.
41
► Guide
Request
The c and lg specify the desired locale and language from supported list.
https://traffic.cit.api.here.com/traffic/6.2/incidents/xml/8/134/86
&c=US
&lg=en
&i18n=true
&localtime=true
&units=metric
Response
The response to the request contains a list of the following:
• TRAFFIC_ITEM: traffic incident information about one active incident
<TRAFFICML_INCIDENTS TIMESTAMP="05/23/2017 13:15:33" VERSION="2.3" TIMESTAMP2="2017-05-23T13:15:33Z"

EXTENDED_COUNTRY_CODE="E0">
<TRAFFIC_ITEMS>
<TRAFFIC_ITEM mid="13901405_reverse">
<START_TIME>May 4, 2017 11:46:25 AM CEST</START_TIME>
<END_TIME>October 31, 2017 11:59:00 PM CET</END_TIME>
<ENTRY_TIME>May 20, 2017 8:45:13 PM CEST</ENTRY_TIME>
<CRITICALITY>
<ID>2</ID>
<DESCRIPTION>minor</DESCRIPTION>
</CRITICALITY>
<ABBREVIATION>
<SHORT_DESC>CONST</SHORT_DESC>
<DESCRIPTION>construction</DESCRIPTION>
</ABBREVIATION>
<COMMENTS>
A5, Kassel - Frankfurt in beiden Richtungen, zwischen Anschlussstelle Alsfeld-West und
Anschlussstelle Homberg (Ohm), Brückenarbeiten, (km 411.3 - km 411.9), Länge: 0.6 km,
Geschwindigkeitsbegrenzung: 80 km/h, bis 31.10.2017
</COMMENTS>
<RDS-TMC_LOCATIONS>
<RDS-TMC>
<ORIGIN>
<LOCATION_DESC>Hegberg</LOCATION_DESC>
<RDS_DIRECTION>-</RDS_DIRECTION>
</ORIGIN>
<TO>
<LOCATION_DESC>Alsfeld-West</LOCATION_DESC>
</TO>
<DIRECTION>+</DIRECTION>
<ALERTC>
42
► Guide
<DESCRIPTION>Bridge maintenance operations</DESCRIPTION>

<PHRASE_CODE>E7</PHRASE_CODE>
<EXTENT>4</EXTENT>
</ALERTC>
<PRIMARY_OFFSET>0.15998</PRIMARY_OFFSET>
<LENGTH>23.41584</LENGTH>
</RDS-TMC>
<LOCATION>
<DEFINED>
<ORIGIN>
<DESCRIPTION TYPE="NTCSA">A5</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">A5</DESCRIPTION>
<DESCRIPTION TYPE="LOCAL">A5</DESCRIPTION>
</ROADWAY>
<POINT ID="11642">
<DESCRIPTION TYPE="NTCSA">Hegberg</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">Hegberg</DESCRIPTION>
<DESCRIPTION TYPE="LOCAL">Hegberg</DESCRIPTION>
<DESCRIPTION TYPE="BNAME">A5</DESCRIPTION>
</POINT>
<DIRECTION ID="0">
<DESCRIPTION TYPE="LOCAL">KASSEL</DESCRIPTION>
<DESCRIPTION TYPE="NTCSA">KASSEL</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">KASSEL</DESCRIPTION>
</DIRECTION>
<PROXIMITY>
<ID>AT</ID>
</PROXIMITY>
</ORIGIN>
<TO>
<DESCRIPTION TYPE="NTCSA">A5</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">A5</DESCRIPTION>
<DESCRIPTION TYPE="LOCAL">A5</DESCRIPTION>
</ROADWAY>
<POINT ID="11646">
<DESCRIPTION TYPE="NTCSA">Alsfeld-West</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">Alsfeld-West</DESCRIPTION>
<DESCRIPTION TYPE="LOCAL">Alsfeld-West</DESCRIPTION>
<DESCRIPTION TYPE="BNAME">A5</DESCRIPTION>
</POINT>
<DIRECTION ID="0">
<DESCRIPTION TYPE="LOCAL">KASSEL</DESCRIPTION>
<DESCRIPTION TYPE="NTCSA">KASSEL</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">KASSEL</DESCRIPTION>
</DIRECTION>
<PROXIMITY>
<ID>AT</ID>
</PROXIMITY>
</TO>
</DEFINED>
<GEOLOC>
<ORIGIN>
</ORIGIN>
<TO>
43
► Guide
</TO>
</GEOLOC>
<NAVTECH>
<EDGE>
</EDGE>
</NAVTECH>
</LOCATION>
<ROAD_CLOSED>false</ROAD_CLOSED>
<EVENT>
<SCHEDULED_CONSTRUCTION_TYPE_DESC>CONSTRUCTION</SCHEDULED_CONSTRUCTION_TYPE_DESC>
<SCHEDULED_CONSTRUCTION_DETAIL>construction</SCHEDULED_CONSTRUCTION_DETAIL>
</EVENT>
<TRAFFIC_ITEM_DESCRIPTION TYPE="short_desc">null, Bridge maintenance operations</
TRAFFIC_ITEM_DESCRIPTION>
<TRAFFIC_ITEM_DESCRIPTION TYPE="desc">, Bridge maintenance operations</TRAFFIC_ITEM_DESCRIPTION>
<TRAFFIC_ITEM_DESCRIPTION TYPE="no_exit_description">Bridge maintenance operations</
TRAFFIC_ITEM_DESCRIPTION>
</TRAFFIC_ITEM>
</TRAFFIC_ITEMS>
</TRAFFICML_INCIDENTS>
Related Information
• Incidents
• Quadkeys
• Supported Languages
Subset of Incident Data

The user wants to obtain traffic incident information near Frankfurt am Main, Germany, .
Note: Instead of using the the bounding box area (bbox), you can use proximity (prox) or corridor
(corridor)
Request
The negBBox parameter restricts the response to an area outside of the specified bounding box and the
maxresults parameter restricts the response to 50 incidents.
https://traffic.cit.api.here.com/traffic/6.2/incidents.xml?bbox=48.8379,8.4375;50.7364,9.84375
&negBBox=37.5000,126.9700;37.4900,126.9800
&status=active
&maxresults=50
44
► Guide
Response
The response to the request contains a list of the following:
• TRAFFIC_ITEM: traffic incident information about one active incident

<TRAFFICML_INCIDENTS TIMESTAMP="05/23/2017 17:23:06 GMT" VERSION="2.3">
<TRAFFIC_ITEMS>
<TRAFFIC_ITEM>
<START_TIME>10/06/2013 22:00:00</START_TIME>
<END_TIME>10/16/2013 12:00:00</END_TIME>
<ENTRY_TIME>10/06/2013 20:25:34</ENTRY_TIME>
<CRITICALITY>
<ID>2</ID>
<DESCRIPTION>minor</DESCRIPTION>
</CRITICALITY>
<COMMENTS></COMMENTS>
<RDS-TMC_LOCATIONS>
<RDS-TMC>
<ORIGIN>
<LOCATION_DESC>Feldatal-Ermenrod</LOCATION_DESC>
</ORIGIN>
<DIRECTION>+</DIRECTION>
<ALERTC>
<DESCRIPTION>(Q)(Baustelle//Baustellen)</DESCRIPTION>
<PHRASE_CODE>E1</PHRASE_CODE>
<EXTENT>0</EXTENT>
</ALERTC>
</RDS-TMC>
<LOCATION>
<DEFINED>
<ORIGIN>
</ROADWAY>
...
<DIRECTION ID="0">
<DESCRIPTION TYPE="LOCAL">ALSFELD</DESCRIPTION>
<DESCRIPTION TYPE="NTCSA">ALSFELD</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">ALSFELD</DESCRIPTION>
</DIRECTION>
<PROXIMITY>
<ID>At</ID>
</PROXIMITY>
</ORIGIN>
<TO>
45
► Guide
</ROADWAY>
...
<DIRECTION ID="0">
<DESCRIPTION TYPE="LOCAL">ALSFELD</DESCRIPTION>
<DESCRIPTION TYPE="NTCSA">ALSFELD</DESCRIPTION>
<DESCRIPTION TYPE="RDSGN">ALSFELD</DESCRIPTION>
</DIRECTION>
<PROXIMITY>
<ID>At</ID>
</PROXIMITY>
</TO>
</DEFINED>
<GEOLOC>
<ORIGIN>
</ORIGIN>
<TO>
</TO>
</GEOLOC>
<NAVTECH>
<EDGE>
...
</EDGE>
</NAVTECH>
</LOCATION>
<ROAD_CLOSED>false</ROAD_CLOSED>
<EVENT>
<SCHEDULED_CONSTRUCTION_TYPE_DESC>
CONSTRUCTION
</SCHEDULED_CONSTRUCTION_TYPE_DESC>
<SCHEDULED_CONSTRUCTION_DETAIL>
construction
</SCHEDULED_CONSTRUCTION_DETAIL>
</EVENT>
<TRAFFIC_ITEM_DESCRIPTION TYPE="short_desc">
bei Feldatal-Ermenrod - Baustelle.
</TRAFFIC_ITEM_DESCRIPTION>
...
</TRAFFIC_ITEM><TRAFFIC_ITEM>
</TRAFFIC_ITEM>
</TRAFFIC_ITEMS></TRAFFICML_INCIDENTS>
Related Information
• Incidents
46
► Guide
Request Flow Availability

The user wants to obtain information about the traffic flow coverage available for the NTdefault profile at
zoom level 10 in the current Traffic API (version 6.0.67.1).
Request
The profile parameter sets the customer profile for the requested coverage.
https://traffic.cit.api.here.com/traffic/6.0/flowavailability.xml
&profile=NTdefault
&zoom=10
Response
• MetaInfo: information about the Map Version and the timestamp of the request
• Profile: customer profile specified in the request
• Region: TMC table ID and region name/IDs

<traffic_flow_availability:GetTrafficCoverageType xmlns:traffic_flow_availability="http://
www.navteq.com/lbsp/LBSP-Traffic-GetCoverage/4">
<Request>
<MetaInfo>
<VerboseMode>-1</VerboseMode>
</MetaInfo>
<Profile>NTdefault</Profile>
</Request>
<Response>
<MetaInfo>
<MapVersion>CDT_WORLD_MAP_ECC_SORTED</MapVersion>
<ModuleVersion>6.0.67.1</ModuleVersion>
<InterfaceVersion>6.0</InterfaceVersion>
<Timestamp>2017-09-27T11:10:33.46:7Z</Timestamp>
</MetaInfo>
<Profile>NTdefault</Profile>
<Region>
<TmcTableId>A0101</TmcTableId>
<Country3>USA</Country3>
<Country2>US</Country2>
<Name>Alabama/Georgia USA</Name>
</Region>
<Region>
<Name>Florida USA</Name>
</Region>
<Region>
<Name>Eastern PA/Southern NJ/Delaware USA</Name>
</Region>
47
► Guide
<Region>
<Name>Western PA/New York USA</Name>
</Region>

</Response>
</traffic_flow_availability:GetTrafficCoverageType>
Note: Adding the mapview parameter to the request, for example

&mapview=50.73818,7.09992;50.73736,7.10123, restricts the response to the specified map
view. So the response contains only information on one region.
Related Information
• Flowavailability
Service Support
If you need assistance with this or any other HERE product, select one of the following options.
• If you have a HERE representative, contact them when you have questions/issues.
• If you manage your applications and accounts through developer.here.com, log into your account
and check the pages on the SLA report or API Health. If this does not clarify the issue, then check
stackoverflow.com/questions/tagged/here-api.
• If you have an evaluation plan, check stackoverflow.com/questions/tagged/here-api.
• If you have questions about billing or your account, Contact Us.
• If you have purchased your plan/product from a HERE reseller, contact your reseller.
48
► API Reference
Chapter 4
API Reference
Topics: This section provides a comprehensive reference to the HERE Traffic
• Resources API.
• Data Types
• HTTP Status Codes
• HTTP Headers
49
► API Reference
Resources
This section provides a comprehensive reference to the Traffic API resources and the parameters supported
by them.
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 13: Parameters for requesting Flow Data
Required Optional
• quadkey, prox, bbox, or corridor (except with Z/X/Y • maxfunctionalclass

address) • 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 on page 28 for complete working URLs.
Resource Parameters
Table 14: 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, see Acquiring Credentials on page 21.
50
► API Reference
app_id xs:string
application.
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
(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 on page 15.
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 Bounding Box Filter on page 30 for an example request using the
responseattributes parameter.
51
► API Reference
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 Traffic Flow Data with DLR on page 32 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 on page 69.
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.
52
► API Reference
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".
• true
• false
By default the value is set to false.
Tiles
This resource processes requests for map tiles reflecting traffic information for a particular geographic area.
The response delivers the map tile as bitmap.
Deprecation Notice
Table 15: Request a Traffic Pattern Tile
Required Optional
• quadkey (used only in a quadkey address) • noContent

• pattern_time • profile
• tables
• res (quadkey address only)
• depth (quadkey address only)
Table 16: Set the Color Depth of a Traffic Tile
Required Optional
• endpoint change (used only in a [Z]/[X]/[Y] address): • noContent
.../{zoom}/{column}/{row}/{size}/{format}? • profile
• quadkey (used only in a quadkey address) • tables
• depth (used only in a quadkey address) • pattern_time

53
► API Reference
Table 17: Set the Size of a Traffic Tile
Required Optional
• endpoint change (used only in a [Z]/[X]/[Y] address): • depth (quadkey address only)
.../{zoom}/{column}/{row}/{size}/{format}? • noContent
• quadkey (used only in a quadkey address) • profile
• res (used only in a quadkey address) • pattern_time

• tables
Table 18: Filter Tile Display by TMC Table
Required Optional
• quadkey (used only in a quadkey address) • depth (quadkey address only)

• tables • noContent
• profile
• pattern_time
Resource Parameters
Table 19: Tile Request Parameters
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 on page 21.
app_code xs:string
depth xs:string
An indicator of tile color depth. The permitted values are:
• 8bit
• 32bit
Used only with quadkey tile addressing.
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
54
► API Reference
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.
profile xs:string
Profile defines such attributes as geographic coverage (TMC tables available for use) and custom
color mapping for tile overlays.
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 on page 15.
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
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 on page 69 for a full list of TMC tables or your customer profile for a list
of tables available to you.
Tile Response Parameters

If a traffic tile request is successful, then it returns a PNG overlay image, as well as the following items
containing additional information about the image:
Table 20: Traffic Response
Attribute Required Description Example
Status Code Yes Server response status code. 200 OK
Cache-Control Yes The max-age value defines how public, max-age=39

long (in seconds) that a tile can
be stored in the client cache.
Expires Yes When this tile expires. Client Tue, 27 Jul 14:59:00 GMT
caches should rerequest tiles
after their expiry time.
55
► API Reference
Attribute Required Description Example
Content-Type Yes The content type of the image/png

response. This can be a PNG
image or plain text, depending
on the request.
Content-Length Yes The size of the response. 7989
Date Yes The date and time when the tile Tue, 27 Jul 14:56:18 GMT
was created.
X- Yes When this tile information was 29 Oct 2015 14:49:32 UTC
LastUpdateFromTrafficAdapter last updated.
X-NLP-IRT No The internal response time of 126273

the request in microseconds.
X-NLP-TID Yes The hashed unique identifier of 5121b4a3-faa6-4f15-

the request. bc25-9e8856a099c6
X-Served-By No Identifier of an instance/server i-4864c4f0.eu-west-1b

which served the request.
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.)
Table 21: Request Traffic Incident Data Using Localization
Required Optional
• quadkey, prox, bbox , or corridor (except with Z/X/Y • criticality

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

incidents.xml/...
See also Examples on page 28 for complete working URLs.
Resource Parameters
Table 23: Incident Request Parameters
app_code xs:string
application.
app_id xs:string
application.
57
► API Reference
(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.
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 on page 71 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
58
► API Reference
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)
• true or 1
• false or 0
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 on page 25 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.
(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 on page 15.
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
59
► API Reference
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
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 on page 69 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)
60
► API Reference
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.
• 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.
Incidents 6.2
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 all incident
endpoints (6.0, 6.1 and 6.2)*.
(* one exception is the type parameter. For mor details see description for this parameter.)
Table 24: Request Traffic Incident Data Using Localization
Required Optional
• quadkey, prox, bbox , or corridor (except with Z/X/Y • criticality

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

incidents.xml/...
The response structure is based on the TML Formal Specification. For more information on TML specification,
contact Technical Customer Support.
See also Examples for complete working URLs.
Resource Parameters
Table 26: Incident Request Parameters
app_code xs:string
app_id xs:string
62
► API Reference
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.
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
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
63
► API Reference
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)
• true or 1
• false or 0
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 on page 25 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
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 on page 15.
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
64
► API Reference
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
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 on page 69 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.3 (traffic/6.2/incidents.<format>
endpoint)
65
► API Reference
verified xs:boolean
A flag indicating if the response is to include or exclude incident reports that have been confirmed.
• 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.
• 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.
Flowavailability
This resource is responsible for handling requests for information about the availability of traffic flow
information.

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/...
The response structure is based on the TML Formal Specification. For more information on TML specification,
contact Technical Customer Support.
See also Examples for complete working URLs.
Request Parameters
Table 27: Availability Request Parameters
app_code xs:string
app_id xs:string
66
► API Reference
id xs:int
A user-defined incident identifier. The response contains the specific incident requested. Any integer
is allowed.
mapview GeoBoundingBoxType: lat,lon; lat,lon
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.
profile xs:string
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.
Meta Resources
The table below documents HERE Traffic API resources that provide API version information, trigger self-tests
on the API or to obtain XSDs.
67
► API Reference
Table 28: Additional Request Parameters
Resource URL variable Description Example Response
version Processes requests for https://traffic.cit.api.here.com/ Service:

version information for traffic/6.0/version Traffic
HERE Traffic API, including Service,
the components that make Version:
up the Traffic Service. 6.0.67.1
exodus.html Triggers a self-test on https://traffic.cit.api.here.com/ 200 Ok

HERE Traffic API. If the traffic/6.0/exodus.html
service is not ready to ?app_id={YOUR_APP_ID}
serve tiles, a 404 error
message results.
xsd incident.xsd Processes a request for https://traffic.cit.api.here.com/ XSD

the incidents XSD. traffic/6.0/xsd/incident.xsd
xsd incident2.2.xsdProcesses a request for https://traffic.cit.api.here.com/ XSD

the incidents version traffic/6.0/xsd/incidents2.2.xsd
2.2 XSD. This version is ?app_id={YOUR_APP_ID}
used with the /traffic/6.1/
incidents endpoint
xsd Processes a request for

incident2.3.1.xsd https://traffic.cit.api.here.com/ XSD
the incidents version traffic/6.0/xsd/incidents2.3.1.xsd
2.3.1 XSD. This version is ?app_id={YOUR_APP_ID}
used with the /traffic/6.2/
incidents endpoint
xsd flow.xsd Processes a request for https://traffic.cit.api.here.com/ XSD

the XSD Schema used for traffic/6.0/xsd/flow.xsd
the flow XSD (traffic flow ?app_id={YOUR_APP_ID}
with predictive data).
Data Types
This section provides a comprehensive reference to data types used throughout the Traffic API.
LatitudeType
This type corresponds to geographic coordinate latitude and represents the location of a place on the
surface of the Earth north or south of the equator.
LatitudeType is a value of the type xs:double with the following restrictions:

• Must satisfy: -90 ≤ value ≤ 90
• Unit: decimal degrees
• Reference System: WGS 84
• Precision: 7 positions after decimal point, additional positions are ignored
68
► API Reference
Query Parameter Representation

Valid examples:
45.1234567
-12.3456789
45.123 -12.3
LongitudeType
This type corresponds to the geographic coordinate longitude and represents the location of a place on the
surface of the Earth east or west of the prime meridian.
LongitudeType is a value of the type xs:double type with the following restrictions:
• Must satisfy: -180 ≤ value ≤ 180
• Unit decimal degrees
• Reference System: WGS 84
• Precision: 7 positions after decimal point, additional positions are ignored

Valid examples:
90.1234567
-120.3456789
90.123 -120.3
FunctionalClassType
Functional class is a road type indicator, reflecting traffic speed and volume, as well as the importance and
connectivity of the road.
FunctionalClassType is a value of the type xs:byte. The following values are supported:
• 1: a road with high volume, maximum speed traffic
• 2: a road with high volume, high speed traffic
• 3: a road with high volume traffic
• 4: a road with high volume traffic at moderate speeds between neighborhoods
• 5: a road whose volume and traffic flow are below the level of any other functional class

Valid examples:
&responseattributes=fc
TMCCodeType
TMCCodeType holds a value of the typexs:string with the following restrictions:
• Fixed length: 5 characters
69
► API Reference
• Format: ECC+CCD+Table, where the following rules apply:
ECC is the Extended Country Code.
CCD is the TMC country code.
Table is the defined TMC Table

A value for the query parameter tables to filter on TMC codes is constructed as shown below.
&tables=ECC+CCD+Table
For example, to filter for the New England region in the USA, concatenate the US extended country code (A0)
with the TMC country code (1) and the New England region table ID (29), producing the following parameter/
value pair:
&tables=A0129
LanguageCodeType
This type is used whenever a language of a value needs to be referenced.
LanguageCodeType is of the type xs:string with the following restrictions:

• Format: Language code compliant with RFC5646

Valid examples:
de
en
LanguageCodeParameterType
This type is used whenever a language filter needs to be specified.
LanguageCodeparameterType is of the type xs:string with the following restrictions:

• Format: Language code following RFC4647

Valid examples:
de
en
CountryCodeType
This type is used whenever a country needs to be referenced for localization.
70
► API Reference
CountryCodeParameterType is of the type xs:string with the following restrictions:

• Format: An ISO 3166-1-alpha-2 country code

Valid examples:
FR
DE
Built-in Resources Types

The HERE Traffic API supports a number of built-in data types described on the following pages.
xs:dateTime
The lexical representation of xs:dateTime consists of finite-length sequences of characters of the following
form:
YYYY + "-" + MM + "-" +

DD + "T" + hh + ":"+
mm + ":" + ss + ("." + s)? +
(zzzzzz)?
Syntax Description
YYYY is a four-or-more digit optionally negative-signed numeral that represents the year; if more than four digits, leading
zeros are prohibited, and '0000' is prohibited
MM is a two-digit numeral that represents the month
DD is a two-digit numeral that represents the day
hh is a two-digit numeral that represents the hour The value 24 is permitted if the minutes and seconds represented are
zero, and the dateTime value so represented is the first instant of the following day (the hour property of a dateTime
object in the value space cannot have a value greater than 23)
mm is a two-digit numeral that represents the minute
ss is a two-integer-digit numeral that represents the whole seconds
s represents the fractional seconds (optional)
zzzzzz represents the timezone
The timezone portion zzzzzz is represented as follows:
(("+" | "-") + hh + ":"+ mm) | "Z"
Syntax Description
"+"|"-" "+" indicates a non-negative duration,
"-" indicates a non-positive duration.
hh is a two-digit numeral (with leading zeros as required) that represents the hours
mm is a two-digit numeral that represents the minutes
71
► API Reference
Syntax Description
"Z" "Z" represent the zero-length duration timezone, UTC "Z" is the canonical representation for UTC dateTime values.
DateTime Example
2002-10-10T12:00:00-05:00 (noon on 10 October 2002, Central Daylight Savings Time as well as Eastern
Standard Time in the U.S.) is 2002-10-10T17:00:00Z, five hours later than 2002-10-10T12:00:00Z.
List ResourceTypes
XML Schema provides a list type allowing more than one item within a single XML element. Items are
separated by space.
The following example defines a list element named "Foo" which contains string elements.
<xs:simpleType name="MyListType">
<xs:list itemType="xs:string"/>
</xs:simpleType>
<xs:element name="Foo" type="MyListType">
A valid instantiation of the "Foo" element would be
<Foo>ABC DEF GHI</Foo>
In this example, the "Foo" element contains the three items "ABC", "DEF", and "GHI".
In representation formats other than XML, the space as separator sometimes becomes unhandy. Therefore, a
standard representation format for list types is defined for each representation format below.

In query strings, items of list types are separated by one of the following characters:
"," (comma) is used at top level
<Foo[0]> + "," + <Foo[1]> + "," + <Foo[2]> + "," + …
";" (semicolon) is used at second level, or if comma is already used in the representation of the list items
<Foo[0]> + ";" + <Foo[1]> + ";" + <Foo[2]> + ";" + …
"!" (exclamation point) is used at third level, or if comma and semicolon are already used in the
representation of the list items
<Foo[0]> + "!" + <Foo[1]> + "!" + <Foo[2]> + "!" + …
The following syntax is introduced as shortcut to represent list types:
<Foo[]>
Note: List types and element sequences are represented in the same manner (see also Sequence of
Same Resource Types Elements on page 73).
72
► API Reference
JSON Representation
List types will be represented as arrays:
[<list[0]>, <list[1]>, <list[2]>, …]
Sequence of Same Resource Types Elements

A schema can define elements which can appear more than once. The following example defines an element
named "Bar" which can be included n times.
<xs:element name="Bar" type="xs:string" maxOccurs="unbounded"/>
A valid instantiation of the "Bar" element would be
<Bar>ABC</Bar><Bar>DEF</Bar><Bar>GHI</Bar>
Element sequences are described in all API documentations with an "[]" as suffix like this:
Bar [] sequence of strings
In representation formats other than XML, listing the same element more than once is inconvenient, so a
standard representation format for sequences is defined for each representation format below.

In query strings, items of list types are separated by one of the following characters:
"," (comma) is used at top level
<Bar[0]> + "," + <Bar[1]> + "," + <Bar[2]> + "," + …
";" (semicolon) is used at second level, or if comma is already used in the representation of the list items
<Bar[0]> + ";" + <Bar[1]> + ";" + <Bar[2]> + ";" + …
"!" (exclamation point) is used at third level, or if comma and semicolon are already used in the
representation of the list items
<Bar[0]> + "!" + <Bar[1]> + "!" + <Bar[2]> + "!" + …
When applying this rule to the above example, the result would be: ABC,DEF,GHI
The following syntax is introduced as shortcut to represent element sequences:
<Bar[]>
Note: list types and element sequences are represented in the same manner. See also List
ResourceTypes on page 72)
73
► API Reference
JSON Representation
Element sequences will be represented as arrays:
[<list[0]>, <list[1]>, <list[2]>,…]
HTTP Status Codes

Traffic API supports the standard HTTP status codes.
Table 29: HERE Error Codes
Error code Description
200 OK Indicates success, but may also be returned when an invalid resource name and/or an invalid
parameter combination has been used in the request.
204 No Content Indicates that the request was valid but there is no traffic data available.
400 Bad request Invalid parameter value in the request, for example zoom out of range. Examples include:
• The quadkey parameter is invalid ([length] 22 or any character not in [0,1,2,3]).

• The required parameters are not provided.
• The query combines both bbox and quadkey parameters, which is not permitted. You must use
either the bbox or quadkey parameter.
• An invalid bbox parameter format. The bbox parameter must be specified in the form [lat0],
[lon0];[lat1],[lon1]
• Incorrect values for the filtering parameters were used.
403 Forbidden Incorrect token in the request. See Acquiring Credentials on page 21 for more information.
404 Not found Unsupported parameter in the request. Examples include:
• The domain-section of the URL does not point at a valid service environment.
• The path-section of the URL does not point at a quadkey service instance.
500 Internal error The service is not available or server configuration issue.
503 Service Unavailable Indicates that the services is temporarily unavailable due to system overload or maintenance
The API supports the standard authorization mechanism common to all HERE APIs. This mechanism can
return status codes detailed below.
Table 30: Authentication Responses
Scenario Response Code HTTP Response Message
app_id and app_code are both 400 The request is missing the app_id and app_code parameters. They
missing must both be passed as query parameters. For information on how to
obtain app_id and app_code, see Acquiring Credentials on page 21
app_id is there but the app_code 400 The request is missing the app_code. It must be passed as a query
is missing parameter.
app_code is there but app_id is 400 The request is missing the app_id. It must be passed as a query
missing parameter.
74
► API Reference
Scenario Response Code HTTP Response Message
app_id and app_code are both 401 This is not a valid app_id and app_code pair. Please verify that the
present in the request but the values are not swapped between the app_id and app_code. For more
validation fails. information, see Acquiring Credentials on page 21
No matching pattern in the 404 The URL resource cannot be found.

authentication mechanism
configuration for this requested
URL
If the requested URL does exist but 405 The HTTP method is not supported for this URL.
the HTTP verb is not supported for
that URL
If SSL is required, but the request 400 SSL/TLS is required for this URL; please retry the request using SSL/TLS.
is not sent over SSL.
Unexpected authentication error 500 Server error - please retry again at a later time.
HTTP Headers
Traffic API supports the standard HTTP headers.
• Expires HTTP Header estimates when fresh data for the requested area will be available next time. It
includes some randomization to spread load.
• ▫ If the estimation was wrong and there is no fresh data, Expires will be set a smaller value that the
customer knows to download data again.
▫ If there are multiple tables in the requested area, TDA Service will send the earliest Expires value.
• Max-age in the Cache-Control HTTP Header will be in sync with Expires.
• Last-Modified will have the latest timestamp from the Traffic Feeds in the requested area.
• ETag is supported for the traffic tiles.
75
► Coverage Information
Chapter 5
Coverage Information
Topics: The HERE Traffic API offers traffic data for the regions described
• Traffic Coverage in Traffic Coverage on page 77. Note that coverage may vary,
• Supported Translation Lang... depending on the customer profile.
For details about traffic coverage available for your customer

profile, contact your HERE representative.
76
Traffic Coverage
The HERE Traffic API offers traffic data for these regions:
Incidents coverage:
Market Country Country

code code
A0101 USA Alabama/Georgia USA
A0102 USA Florida USA
A0103 USA Eastern PA/Southern NJ/Delaware USA
A0104 USA Western PA/New York USA
A0105 USA Northern CA/Nevada USA
A0106 USA Southern CA and Las Vegas USA
A0107 USA Illinois/Indiana/Wisconsin USA
A0108 USA Michigan/Ohio USA
A0110 USA Virginia/Maryland/North Carolina/South Delaware USA
A0111 USA Northern Texas/Oklahoma USA
A0112 USA Southern Texas USA
A0113 USA AR/LA/MS/TN USA
A0114 USA Oregon/Washington USA
A0115 USA Arizona/New Mexico/Texas USA
A0116 USA Colorado/Utah USA
A0117 USA Idaho/Montana/Wyoming USA
A0118 USA North Central States USA
A0119 USA Kansas/Missouri/Southern Illinois USA
A0120 USA New York/Northern NJ/Connecticut USA
A0121 USA Kentucky/Tennessee/Indiana USA
A0122 USA Ohio/West Virginia USA
A0125 USA North Carolina/South Carolina USA
A0126 USA Hawaii USA
A0129 USA New England USA
A0133 USA Alaska USA
A0832 PRI Puerto Rico
A1C09 CAN Ontario Canada
A1C23 CAN British Columbia Canada
77

code code
A1C24 CAN Quebec Canada
A1C27 CAN Alberta Canada
A1C28 CAN Manitoba Canada
A1C30 CAN NB, NS, PEI Canada
A1C31 CAN Saskatchewan Canada
A1C34 CAN Newfoundland and Labrador Canada
A1C35 CAN Yukon-Nunavut Canada
A2B14 BRA Sul, Sudeste Brazil
A2B15 BRA Norte, Nordeste, Centro-Oeste Brazil
A5F36 MEX Mexico
D0A17 ZAF South Africa
E0501 ITA Italy
E0601 BEL Belgium
E0A01 AUT Austria
E0B01 HUN Hungary
E0D01 DEU Germany
E1118 GRC Greece
E1409 CHE Switzerland
E1617 FIN Finland
E1909 DNK Denmark
E1C07 GBR United Kingdom
E1F32 FRA France
E2225 CZE Czech Republic
E2305 POL Poland
E2E17 ESP Spain
E2F49 NOR Norway
E3242 IRL Ireland
E3339 TUR Turkey
E3340 TUR Turkey
E3817 NLD Netherlands
E3C33 HRV Croatia
E3E33 SWE Sweden
E4842 PRT Portugal
E4933 SVN Slovenia
F0153 AUS Canberra, CT Australia
78

code code
F0254 AUS Sydney, NSW Australia
F0301 AUS Melbourne, V Australia
F0456 AUS Brisbane, Q Australia
F0557 AUS Adelaide, SA Australia
F0658 AUS Perth, WA Australia
E0723 RUS Moscow Russia
E0724 RUS St. Petersburg Russia
E0725 RUS Yekaterinburg Russia
F1941 NZL New Zealand
Flow coverage:

code code
A0101 USA Alabama/Georgia USA
A0102 USA Florida USA
A0103 USA Eastern PA/Southern NJ/Delaware USA
A0104 USA Western PA/New York USA
A0105 USA Northern CA/Nevada USA
A0106 USA Southern CA and Las Vegas USA
A0107 USA Illinois/Indiana/Wisconsin USA
A0108 USA Michigan/Ohio USA
A0110 USA Virginia/Maryland/North Carolina/South Delaware USA
A0111 USA Northern Texas/Oklahoma USA
A0112 USA Southern Texas USA
A0113 USA AR/LA/MS/TN USA
A0114 USA Oregon/Washington USA
A0115 USA Arizona/New Mexico/Texas USA
A0116 USA Colorado/Utah USA
A0117 USA Idaho/Montana/Wyoming USA
A0118 USA North Central States USA
A0119 USA Kansas/Missouri/Southern Illinois USA
A0120 USA New York/Northern NJ/Connecticut USA
A0121 USA Kentucky/Tennessee/Indiana USA
A0122 USA Ohio/West Virginia USA
A0125 USA North Carolina/South Carolina USA
79

code code
A0126 USA Hawaii USA
A0129 USA New England USA
A0133 USA Alaska USA
A0832 PRI Puerto Rico
A1C09 CAN Ontario Canada
A1C23 CAN British Columbia Canada
A1C24 CAN Quebec Canada
A1C27 CAN Alberta Canada
A1C28 CAN Manitoba Canada
A1C30 CAN NB, NS, PEI Canada
A1C31 CAN Saskatchewan Canada
A1C34 CAN Newfoundland and Labrador Canada
A1C35 CAN Yukon-Nunavut Canada
A2A47 ARG Argentina
A2B14 BRA Sul, Sudeste Brazil
A2B15 BRA Norte, Nordeste, Centro-Oeste Brazil
D0A17 ZAF South Africa
E0301 AND Andorra
E0501 ITA Italy, San Marino, Vatican City
E0601 BEL Belgium
E0723 RUS Moscow Russia
E0724 RUS St. Petersburg Russia
E0725 RUS Yekaterinburg Russia
E0726 RUS Nizny Novgorod Russia
E0727 RUS Krasnodar, Rostov-on-Don, Sochi, Stavropol
E0728 RUS Novosibirsk, Krasnoyarsk, Kemerovo, Irkutsk, Vladivostok
E0A01 AUT Austria
E0B01 HUN Hungary
E0D01 DEU Germany
E1118 GRC Greece
E1409 CHE Switzerland and Liechtenstein
E1617 FIN Finland
E1701 LUX Luxembourg
E1801 BGR Bulgaria
E1909 DNK Denmark
80

code code
E1C07 GBR United Kingdom, Jersey, Guernsey and Isle of Man
E1E01 ROU Romania
E1F32 FRA France and Monaco
E2225 CZE Czech Republic
E2305 POL Poland
E2551 SVK Slovakia
E2C43 LTU Lithuania
E2E17 ESP Spain and Gibraltar
E2F49 NOR Norway
E3242 IRL Ireland
E3339 TUR Turkey
E3340 TUR Turkey
E3817 NLD Netherlands
E3951 LVA Latvia
E3C33 HRV Croatia
E3E33 SWE Sweden
E4259 EST Estonia
E4633 UKR Ukraine
E4933 SVN Slovenia
F0153 AUS Canberra, CT Australia
F0254 AUS Sydney, NSW Australia
F0301 AUS Melbourne, V Australia
F0456 AUS Brisbane, Q Australia
F0557 AUS Adelaide, SA Australia
F0658 AUS Perth, WA Australia
F0759 AUS Hobart, TAS Australia
F0860 AUS Darwin, NT Australia
F0926 SAU Saudi Arabia
F0E58 BHR Bahrain
F0F05 MYS Kuala Lumpur, Johor Bahru Malaysia
F1626 OMN Oman
F1941 NZL New Zealand
F1D10 TWN Taiwan
F2130 KWT Kuwait
F2252 QAT Qatar
81

code code
F2502 IND Central India
F2503 IND South India
F2504 IND North India
F2732 VNM Vietnam
F2834 PHL Philippines
F2A10 SGP Singapore
F2C23 IDN Jakarta Indonesia
F2D19 ARE United Arab Emirates (Dubai- Abu Dhabi- Sharjah)
F3219 THA Thailand
Supported Translation Languages

The supported languages for incident translation are:
• English (en)
• French (fr)
• Spanish (es)
• German (de)
• Italian (it)
• Swedish (sv)
• Danish (da)
• Norwegian (no)
• Finnish (fi)
• Dutch (nl)
• Slovak (sk)
• Polish (pl)
• Russian (ru)
• Turkish (tr)
• Portuguese (pt)
82

Traffic API v6.0.67.1 Developer's Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Traffic API v6.0.67.1 Developer's Guide

Uploaded by

Copyright:

Available Formats

Traffic API

Name: Traffic API

Version: Version 6.0.67.1

Name: Traffic API Developer's Guide

Date: 2017-Oct-09, 15:56 (GMT)

Selecting a Tile Color Depth............................................................................................................................................................... 38

What Is the Traffic API?

Why Use the Traffic API?

Table 1: Main features of the HERE Traffic API

Requesting Traffic Incident Data

• a timestamp of the obtained traffic data

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

The Mercator Projection

The basic Mercator projection formula is this:

{λ, φ} -> x[-1, 1] y [-1, 1]

col1,z+1 = (2*colz) + 1row1,z+1 = (2*rowz) + 1

col = column number in the tile

row= row number in the tile grid

The diagram below demonstrates this graphically:

Figure 1: Tiles at different zoom levels

--- javascript ---

latRad = lat * Math.PI / 180;

--- output ---

// Convert the column (x) and row (y) values

// Interleave the binary values (b), convert the

--- input ---

--- JavaScript ---

if ((yTile & mask) != 0) {

--- output ---

Traffic Flow Data Limitations

Traffic Tiles and Zoom Level

• The traffic flow detail changes with the zoom level.

Figure 2: Zoom level too low to show traffic

Figure 3: Zoom level 8 begins to show traffic flow overlay

Figure 4: Zoom level 14 shows more detailed traffic flow overlay

Traffic Incident and Zoom Level

• No display of traffic incident information: zoom levels 0-7

Table 2: Acronyms and Definitions

FI The entry for each Flow Item in the specified direction.

Table 3: Basic request elements

Element Value/Example Purpose Description/comments

Base URL https://tiles.traffic.api.here.com Tiles Production environment.

https://traffic.api.here.com Incidents, Flow, or Flow

https://tiles.traffic.cit.api.here.com Tiles CIT environment

https://traffic.cit.api.here.com Incidents, Flow, or Flow For more information

Path /traffic/6.0/ For tiles and

/traffic/6.2/ For incidents resource

/traffic/6.2/ For flow resource

Resource tiles To obtain traffic map tiles Name of a resource.

Only the GET method is

Element Value/Example Purpose Description/comments

Quadkey, [Z]/[X]/[Y], Bounding Box, Corridor or Traffic Incidents

Customer Profile or Mapview Traffic Flow Availability

Application &app_code={YOUR_APP_CODE} All requests Substitute your own

Application Id &app_id={YOUR_APP_ID} All requests Substitute your own

For further information, see Examples.

HERE Server Environments

High Loads and Performance Testing

Filtering TMC Tables

For a list of sample TMC codes, see Traffic Coverage .

Filtering Traffic Flow Data

Filtering Traffic Incident Data

Incident Types and Filtering

col1,z+1 = (2colz) + 1row1,z+1 = (2rowz) + 1