Sorry, you need to enable JavaScript to visit this website.

TomTom Traffic Flow - Intermediate Service - DatexII

Introduction to the TomTom Traffic Flow – Intermediate Service – DATEX II

Executive summary

The TomTom Traffic Flow – Intermediate Service – DATEX II (hereafter called ‘Service’) is designed for server to server integration with traffic control center, routing, navigation, and mapping applications. It contains real-time travel times and speeds for segments, based on TomTom’s Traffic technology, with several possible granularities.

In this document, we discuss how to access the service and the features that are included. TomTom only supports the Intermediate Service with the use of the TomTom customized DATEX II schema, available for download from our website (linked previously and later in this document). Using the Service with the standard DATEX II schema will disable the functionality that is included with the Service. Therefore, the standard DATEX II schema is not supported.

Scope

This page gives basic information on the Service and shows how to configure this to work with your environment. Basic knowledge of installing and using XML-based schemas is necessary.

Intended audience

This information is intended to be used by TomTom partners and customers (decision makers and developers).

What is the TomTom Traffic Flow – Intermediate Service – DATEX II?

Standard configurations

TomTom offers traffic flow data to customers. The most basic data type is speed information and travel times, by segment. TomTom configures a custom product based upon your specific needs. The product is static, so included regions and features are fixed, once the product is configured.

Optional configurations

The Service gives users traffic flow data with highly customizable configuration options. When the product is configured, there are some additional options that could be enabled, depending on your specific preferences.



Option Description

Closure field

A flag to indicate whether a road segment is closed. When enabled, a special <roadClosure/> field appears. If a road segment is closed, the average speed is the current speed. If this option is not enabled, the average speed shown will be zero for segments affected by a road closure.

Relative speed

When enabled, the relative speed is provided. This is defined as the ratio of average speed to free-flowing speed (for example, 0.250 indicates a current real-time speed that is 25% of freeflow speed).

Traffic condition

When enabled, the current traffic condition is given. This is expressed by one of up to eight available values, for example, heavyTraffic or stationaryTraffic.

Miles per hour

The average speed is additionally provided in mph (all speeds are provided by default in km/h).

Map version

Provides names and versions of the maps that were used to create the content.

RESTful API

The Service uses RESTful API (Representation State Transfer) technology. Because you only need to use one URL, the service is simple to use.

‘Simple HTTP server’ profile

The interface supports the client pull method, also known as the 'simple HTTP server' profile. The profile is described in the Software Developers Guide and Exchange Platform Specific Model (see www.datex2.eu for details). TomTom does not support the SOAP envelope, described in the Software Developers Guide.

How do you make a request?

To make a request, the URL should be constructed as shown in the following sections. Note: requests may not function if made from a non-authenticated computer. More details are available in the section, “A secure connection” at https://developer.tomtom.com/intermediate-traffic-service

Format

The sample URL is formatted as follows:

https://<baseURL>/tsq/hdf/<productName>/<key>/content.xml[?flowType=<flowType>]

The following is an example URL:

https://traffic.tomtom.com/tsq/hdf/DEU-HDF-OPENLR/<APIKEY>/content.xml

Parameters

The following table provides a detailed explanation of the available fields that were previously shown in the Format section.





Field Description Req'd? Type / values

baseURL

Base URL for calling the API.

Yes

traffic.tomtom.com

productName

Name of the product (feed) you are requesting. These will be indicated to you as part of the provisioning process. Typically, it explains the country (country code), type of feed (HDF is the flow feed) and the location referencing method (TMC or OpenLR).

Yes

e.g.
DEU-HDF-TMC
DEU-HDF-OPENLR

key

Authorization key for access to the API.

Yes

String

[flowType]

When the feed is requested without parameter 'flowType' it contains ALL messages covered by the feed. In that case, the field averageSpeed in a message represents the current speed for congested road segments and the free-flow speed for non-congested road segments.

By using the 'flowType' parameter, the response can be shaped to only support a certain speed type. This also affects the number of messages in the response. There are two values supported for this parameter:

  • ff, gets the messages for ALL road segments covered by the feed. The field averageSpeed in the message provides the free-flow speed for the affected road segment.

  • nff, only gets the messages for road segments that are NOT in a free-flow state. The field averageSpeed of a message provides the currently measured speed for the affected road segment.

When using this parameter, at the first request the free-flow information should be downloaded. Afterwards, non-free-flow information can be downloaded for each future request. The free-flow and non-free-flow data is related. The segments for both files should be in sync, otherwise there is a mismatch in the locations of the free-flow data. Therefore, every time the non-free-flow information is downloaded, it must be checked. This insures that the non-free-flow data corresponds to the freeflow data (that the user already has).

The verification is done by confirming the <nationalIndentifier> within <publicationCreator> in DATEX II format. If the <nationalIndentifier> of the non-free-flow content does not match the <nationalIndentifier> of the free-flow content that was downloaded with the first request, the free-flow information must be re-requested.

No

flowType=nff
flowType=ff

Recommended HTTP headers

Since flow feeds can be very large, TomTom recommends optimizing the information transmission as much as possible. By doing this, the client receives more up-to-date information.

If-Modified-Since
TomTom recommends using the standard HTTP header If-Modified-Since with the last value of Last-Modified received. When this header is used properly, you avoid unnecessarily downloading identical content. For details, see HTTP/1.1 standard (RFC2616 section 14.25).

Accept-Encoding: Gzip
The TomTom Traffic Flow bulk feed supports gzip compression of all response types. However, responses are compressed only when the requester states gzip support. This should be specified through the standard HTTP header Accept-Encoding: gzip. TomTom recommends using this header type as it significantly reduces the payload size.

Response you receive after a request is made.

Response example

If you make the following request:

https://traffic.tomtom.com/tsq/hdf/DEU-HDF-OPENLR/<APIKEY>/content.xml?flowType=nff

You can expect the following response:

<?xml version="1.0"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/1_0/1_0" modelBaseVersion="1.0">
  <exchange>
    <supplierIdentification>
      <country>nl</country>
      <nationalIdentifier>TomTom Traffic Service</nationalIdentifier>
    </supplierIdentification>
  </exchange>
  <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="ElaboratedDataPublication" lang="en">
    <publicationTime>2015-12-23T11:54:00Z</publicationTime>
    <publicationCreator>
      <country>other</country>
      <nationalIdentifier>db14af1d-3827-4d61-8525-8f70bc1c5b3f15e87601</nationalIdentifier>
    </publicationCreator>
    <headerInformation>
      <confidentiality>internalUse</confidentiality>
      <informationStatus>real</informationStatus>
    </headerInformation>
    <referenceSettings>
      <locationSetReference/>
    </referenceSettings>
    <elaboratedData id="Ob719eb226ba9b25e44b15b17">
      <basicDataValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TravelTimeValue">
        <supplierCalculatedDataQuality>95.0</supplierCalculatedDataQuality>
        <affectedLocation>
          <locationContainedInGroup xsi:type="LocationByReference">
            <locationExtension>
              <openlr>
                <binary>CwcZ6yJrqQslDgRLAQULFw==</binary>
              </openlr>
            </locationExtension>
            <predefinedLocationReference>OpenLR</predefinedLocationReference>
          </locationContainedInGroup>
        </affectedLocation>
        <travelTime>346.0</travelTime>
        <travelTimeValueExtension>
          <averageSpeed>9.0</averageSpeed>
          <relativeSpeed>0.257</relativeSpeed>
          <trafficCondition>queuingTraffic</trafficCondition>
        </travelTimeValueExtension>
      </basicDataValue>
    </elaboratedData>
    [...]
  </payloadPublication>
</d2LogicalModel>

Response – DATEX II payload specification (analysis of the output received)

The payload in the output is formatted as DATEX II, which is a European standard for the exchange of Traffic and Travel Information. TomTom supports version 1. The DATEX II User Guide version 1.0 and the standard DATEX II XML schema version 1.0 are available from the DATEX II website (www.datex2.eu). Recommended documents are:

DATEX II User Guide version 1.0 (DATEXIIv1.0-UserGuide_v1.0.pdf)

A browsable DATEX II version 1.0 data dictionary (DATEXIIv1.0-DataDictionnary_v1.0.zip)

The Elaborated Data Publication, used by TomTom, is described in more detail in section 4.11 of the DATEX II User Guide version 1.0.

TomTom extended the data model with additional fields; the full XSD schema including extensions can be downloaded by clicking this link. It is a "Level B" extension of the standard XML schema: DATEXIISchema_1_0_1_0.xsd. Such an extension is interoperable with the "Level A" data model (see section 2.2.3 in the DATEX II User Guide version 1.0 for more information).

Standard information

The following table shows the fields offered in our standard configuration. The features are standard DATEX II elements and TomTom specific extensions. For our purposes, ‘congestion’ is defined as traffic that may cause a non-freeflow condition.




Field Name (part of) Description Further details

affectedLocation (TravelTimeValue)

A definition of a segment of a road in a particular direction.

The segment identifier, for explanation, see Geographical representation.

travelTime (TravelTimeValue)

Current average travel time in seconds based on real-time measurements on the affectedLocation.

Only provided in case of congestion. For explanation, see TravelTime and averageSpeed.

averageSpeed (TravelTimeValueExtensionType)

Current average speed on the affectedLocation, in km/h, directly based on the travelTime and the length of the affectedLocation.

Only provided in case of congestion; it is an extension of TravelTimeValue. For explanation, see TravelTime and averageSpeed.

freeFlowTravelTime (TravelTimeValue)

The travel time in seconds that is expected under ideal freeflow conditions.

Only provided in case of free flow conditions. For explanation, see Freeflow and FreeFlowTravelTime and freeFlowSpeed.

freeFlowSpeed (TravelTimeValue)

The freeflow speed in km/h that is expected under ideal freeflow conditions, corresponding to the freeFlowTravelTime.

Only provided in case of freeflow conditions. For explanation, see Freeflow and FreeFlowTravelTime and freeFlowSpeed.

supplierCalculatedDataQuality (BasicDataValue)

A measure of data quality assigned to the value by the supplier. 100% equates to perfect quality.

For explanation, see SupplierCalculatedDataQuality.

Freeflow

For every segment, an estimate is made whether traffic is flowing freely or whether it is congested. If traffic is flowing freely, the actual travel time depends on the type of vehicle and the speed driven. The actual speeds on each segment can differ greatly. In this case, the TravelTimeValue will contain the <freeFlowSpeed> and <freeFlowTravelTime>. If traffic is not flowing freely, it is considered congested, and a driver cannot choose the speed anymore. In that case, the TravelTimeValue will contain the <travelTime> and <averageSpeed>.

TravelTime and averageSpeed

The <travelTime> contains an estimate of the real-time travel time between the start and the end of the affected location. It is the instantaneous travel time, which means that it is the sum of the travel time estimations on the individual road segments of the affected location. Note that this may differ from the actual travel time, when measured from the start to the end of the affected location (especially for longer segments). The reason for this difference is because the travel time estimate is based on both real-time measurements and historic data. It provides speeds by the day of the week and the time of day. The <averageSpeed> is directly derived from the provided travelTime and the length of the affectedLocation. Therefore, the <supplierCalculatedDataQuality> also applies to this value.

In case the roadClosure flag is not configured for the product, and the affected location is closed, averageSpeed is set to 0 km/h and the travelTime refers to the travel time under freeflow conditions.

FreeFlowTravelTime and freeFlowSpeed

The <freeFlowTravelTime> is directly derived from the freeFlowSpeed and the length of the affectedLocation. The <freeFlowSpeed> is the expected speed under freeflow conditions, based on historic data. It is averaged over different vehicle types. The value is capped by the speed limit.

SupplierCalculatedDataQuality

This field contains a quality measure for the provided travel time and speed. It is based on the following variables:

  • the number of real-time measurements from devices driving the affected locations at the moment
  • the standard deviation of the measurements
  • the percentage of the affected location that is covered with measurements
  • compatibility of measurements with historic data
  • the age of the measurements

When we determine that an insufficient amount of real-time measurements are available, historic data is given a greater weight in the travel time estimate. If the value of <supplierCalculatedDataQuality> is below 60% (0.6), then the historic data holds greater importance in the calculation. A value of 50% (0.5) implies that the provided travel time is based only on the historic speed profile.

Optional information

The DATEX II data model has been extended to allow additional parameters. The Service has the following possible extensions. Additional details are shown in Optional.




Option Implementation Example

Miles per hour

Average speed in miles per hour.

This feature is represented by element averageSpeedInMPH provided in complex type TravelTimeValueExtensionType.

 

Road closure

Indicator showing that the affected location is closed.

This feature is represented by element roadClosure provided in complex type TravelTimeValueExtensionType.

 

Relative speed

The relative speed is the relationship between the average speed and the freeflow speed. The range is from 0 to 1 and is precise to three decimal places. If the relativeSpeed value is 0, the actual average speed is 0. If the relativeSpeed value is 1, then the average speed and freeflow speed are equal.

This feature is represented by element relativeSpeed provided in complex type TravelTimeValueExtensionType.

This field is only provided in case of congestion.

 

Traffic condition

Traffic status according to the relative speed of the location. It is represented by element trafficCondition provided in complex type TravelTimeValueExtensionType and it can be any of the following values:

  • freeTraffic
  • longQueuesTraffic
  • heavyTraffic
  • slowTraffic
  • queuingTraffic
  • stationaryTraffic
  • closed
  • unknown
 

Map version

This feature is supported by element mapVersion in complex type PayloadPublicationExtensionType.

<?xml version="1.0" ?>
<d2LogicalModel
    xmlns="http://datex2.eu/schema/1_0/1_0"
    modelBaseVersion="1.0">
    [...]
    <payloadPublication
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="ElaboratedDataPublication" lang="en">
        [...]
        <payloadPublicationExtension>
            <mapVersion>eur2018.06</mapVersion>
        </payloadPublicationExtension>
        <!-- list of elaborated data elements follows -->
        [...]
    </payloadPublication>
</d2LogicalModel>

Geographical representation

Geographical representation of the road segments is an important part of the payload. There are two geographical representations that are supported: TMC and OpenLR. Since OpenLR prevents interpretation differences, licensing costs, map dependencies, or version dependencies, TomTom recommends using OpenLR instead of TMC. TMC based data is still offered for customers with existing platforms that need compatibility with their legacy systems.

The data type of the affectedLocation in the schema is a Group of Locations. LocationByReference is the location method used, and it contains the identifier of a predefinedLocationReference. If we use TMC, the predefinedLocationReference is a TMC link identifier. If we use OpenLR, the actual location reference information is provided in TomTom’s proprietary extension LocationExtensionType and the predefinedLocationReference is constantly set to “OpenLR.”

Location referencing method Example

OpenLR

<affectedLocation>
  <locationContainedInGroup xsi:type="LocationByReference">
    <locationExtension>
      <openlr>
        <binary>CwANeSUjyAENIAFw+aQBAA==</binary>
      </openlr>
    </locationExtension>
    <predefinedLocationReference>OpenLR</predefinedLocationReference>
  </locationContainedInGroup>
</affectedLocation>

TMC

<affectedLocation>
  <locationContainedInGroup xsi:type="LocationByReference">
    <predefinedLocationReference>LD01+27442</predefinedLocationReference>
  </locationContainedInGroup>
</affectedLocation>

OpenLR is an open source location referencing system for all roads. OpenLR is a dynamic location reference method that can reference the complete digital map. The location references use the binary format version 3 that is described in the OpenLR White Paper. An open source reference implementation can be downloaded on the OpenLR website (www.openlr.org). TomTom also offers support for third parties to implement and test their own implementation.

Traffic Message Channel (TMC)

When using TMC as a geographical representation, travel times are measured by a TMC link. A TMC link is part of a TMC path. A TMC link is a sequence of road elements that starts at a TMC location, and ends at a next TMC location in the TMC table in the specified direction. You can recognize a TMC link by:

  • TMC table (CountryCode, LocationTableNumber, version).
  • Primary TMC location, defining the TMC point location at the end of the TMC link.
  • Direction, as defined by the TMC path.
  • An indication of the inclusion of internal / external road segments (see below).
  • An optional extent (the default value is 1).

Generally, the set of TMC link identifiers that can be used in an ElaboratedDataPublication is static. That means that in subsequent ElaboratedDataPublications, the same locations will be used. However, this is not always the situation. Sometimes, the set of the used TMC link identifiers can be changed. This occurs when a new TMC table is introduced.

referenceSettings

For TMC – based data, the referenceSettings contain a locationSetReference. Here, a reference is made to a specific version of a TMC location table. The format is: A + BB + "v" + C + "." + D, where:

  • A = the Country Code (hex format)
  • BB = the Location Table Number (2 digits)
  • C = the major version number (1 or 2 digits)
  • D = the minor version number (1 or 2 digits)

Example:

<referenceSettings>
  <locationSetReference>D01v7.1</locationSetReference>
</referenceSettings>

TMC link identifier

In TMC – based DATEXII, TMC chain information includes the following parts ACVVDLLLLL[xE[E]]:



Part Description

A

Fixed letter 'L'

C

Hexadecimal country code as described in IEC 62106.

VV

TMC Location Table code

D

TMC direction of the chain (defined by the TMC path). For possible values, see TMC direction.

LLLLL

TMC point location code. If the number is not five digits long, zeros are added at the beginning until there are five digits.

[xE[E]]

Either empty, when extent = 1, or fixed letter 'x' followed by the extent (one or two digits)

Using the specified TMC table, the secondary location (start of the stretch) can be found from the primary location, the direction and the extent. C, VV and LLLLL correspond to the TMC Location Reference, which is a unique identifier for a TMC location.

TMC direction

The possible values for D infer the direction of travel (secondary to primary location) along the TMC path:




Value Direction Validity

p (lower case)

Positive

Internal + External

n (lower case)

Negative

Internal + External

+

 

External

-

Negative

External

P (upper case)

Positive

Internal

N (upper case)

Negative

Internal

If the extent > 1 then the value for direction must be 'p' or 'n', including all internal and external road segments. See Internal and external road segments for more details.

Internal and external road segments

To know exactly where a TMC link starts and ends, you should understand the concept of internal and external road segments. For each TMC point location and each direction, a composition is made of road segments that are part of the TMC location. An example of this is a highway junction or the roads between the exit and the entry. These are the internal road segments. Furthermore, a path of road segments is constructed, connecting the TMC locations. The road segments between two TMC locations are the external road segments, which are assigned to the TMC location where the path is leading.

If two consecutive TMC locations have an overlap or a reverse order in the TomTom map, they can be combined into one TMC link with an extent > 1. Typically, a TMC link includes both the internal and external road segments of a TMC location, so a TMC link usually starts at the end of the secondary location and ends at the end of the primary location. Exceptionally, the travel time is provided just for the internal road segments or the external road segments. This is indicated in the TMC link identifier.

Examples

In this section, we demonstrate how to resolve TMC link identifiers on the receiver side. Here we map to a definition of each of the fields within the link identifier. We also show how to use the extent to find the secondary location.

Example 1: L817n39984x2

Given TMC location data:

  • country code: 8
  • location table number: 17
  • direction from secondary to primary location: negative
  • primary location ID: 39984
  • extent: 2

How to interpret TMC location data to resolve the secondary location:

  1. Invert direction: positive -> negative.
  2. Since the resolved direction is positive, follow the positive offset path for 39984 in TMC table for two extents
  3. You will find the subsequent positive offsets are 39985 and 39986, hence, the resolved secondary location is 39986

Example 2: LD01+27442

Given TMC location data:

  • country code: D
  • location table number: 1
  • direction from secondary to primary location: positive (external only)
  • primary location ID: 27442
  • extent: 1 (if the extent is not provided explicitly then it is 1)

How to interpret TMC location data to resolve the secondary location:

  1. Invert direction: positive -> negative.
  2. Since the resolved direction is negative, follow the negative offset path for 27442 in the TMC table for one extent.
  3. You will find the subsequent negative offset is 30080.
  4. Now follow the path for 27442 in that direction and only select segments that are marked as the external part of 27442.

Predefined Location Product

In DATEX II, a PredefinedLocationsPublication is used to predefine a set of locations, that can then be referred to in the <elaboratedDataPublication>. This allows for simplification of the elaborated data publication, where typically, the elaborated data is published for a fixed set of locations that is then published separately. However, since there is a straightforward relationship between the predefined location reference we use, and the corresponding TMC link, the Predefined Location Product is not published.

You are here