Intermediate Traffic Evaluation API - Traffic Flow

Purpose

This endpoint is part of the self-service Intermediate Traffic Evaluation API, intended for exploring TomTom traffic flow data ahead of a production integration with the Intermediate Traffic API.

The TomTom Traffic Flow - Intermediate Service - Protobuf (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 configurations.

This document describes the data exchange method and the payload description of the Service interface.

Features

TomTom provides customers with real-time travel times and speeds for segments.

Detailed information about the available features can be found in the section Available features.

Request data

How do you make a request?

For ease of viewing and identification:

• Constants and parameters enclosed in curly brackets { } must be replaced with their values.
• Please see the following Request parameters and Request headers sections with the required and optional parameters tables for their values.

The generic request format is as follows:

https://api.tomtom.com/maps/orbis/intermediate-traffic/flow-detailed/{cityName}/content.proto[?flowType={flowType}]

The following shows an example cURL request with the required headers:

1curl --request GET --compressed \
2  --url "https://api.tomtom.com/maps/orbis/intermediate-traffic/flow-detailed/{cityName}/content.proto" \
3  --header "TomTom-Api-Key: {yourTomTomApiKey}" \
4  --header "TomTom-Api-Version: 1" \
5  --header "Accept-Encoding: gzip" \
6  --output content.proto

Request parameters

The following table provides a detailed explanation of the available fields that were previously shown in the How do you make a request? section.

Request headers

The following table provides a detailed explanation of the available headers that were previously shown in the How do you make a request? section.

Response data

Response codes

Response example

If you make the following request:

https://api.tomtom.com/maps/orbis/intermediate-traffic/flow-detailed/amsterdam/content.proto?flowType=nff

You can expect a response that contains protocol buffers binary data. The textual representation of this data could look like this:

1metaInformation {
2  createTimeUTCSeconds: 1772619030
3  supplierAndClientInfo {
4    clientID: "e28bc9d4-4e05-4918-b662-2562029599565a2f2136"
5    supplierID: "TomTom Traffic Service"
6  }
7  mapVersion: "eur2026.01.140"
8}
9[...]
10trafficFlowWithPredictionPerSection {
11  location {
12    openlr: "\013\003\276\347%;\3673\325\027\371\332\376\3552\005"
13    lengthInMeters: 1372
14  }
15  speedVector {
16    minutesInFuture: 0
17    sectionSpeed {
18      startOffsetInMeters: 0
19      speed {
20        averageSpeedKmph: 39
21        travelTimeSeconds: 48
22        confidence: 81
23        relativeSpeed: 0.975
24        trafficCondition: FREE_TRAFFIC
25      }
26    }
27    sectionSpeed {
28      startOffsetInMeters: 520
29      speed {
30        averageSpeedKmph: 22
31        travelTimeSeconds: 102
32        confidence: 97
33        relativeSpeed: 0.741
34        trafficCondition: FREE_TRAFFIC
35      }
36    }
37    sectionSpeed {
38      startOffsetInMeters: 1129
39      speed {
40        averageSpeedKmph: 38
41        travelTimeSeconds: 23
42        confidence: 100
43        relativeSpeed: 1
44        trafficCondition: FREE_TRAFFIC
45      }
46    }
47  }
48  speedVector {
49    minutesInFuture: 15
50    sectionSpeed {
51      startOffsetInMeters: 0
52      speed {
53        averageSpeedKmph: 27
54        travelTimeSeconds: 181
55        relativeSpeed: 0.803
56        trafficCondition: FREE_TRAFFIC
57      }
58    }
59  }
60  speedVector {
61    minutesInFuture: 30
62    sectionSpeed {
63      startOffsetInMeters: 0
64      speed {
65        averageSpeedKmph: 26
66        travelTimeSeconds: 192
67        relativeSpeed: 0.756
68        trafficCondition: FREE_TRAFFIC
69      }
70    }
71  }
72  speedVector {
73    minutesInFuture: 45
74    sectionSpeed {
75      startOffsetInMeters: 0
76      speed {
77        averageSpeedKmph: 26
78        travelTimeSeconds: 193
79        relativeSpeed: 0.753
80        trafficCondition: FREE_TRAFFIC
81      }
82    }
83  }
84}
85[...]

Response - Protobuf payload specification (analysis of the received output)

Protocol buffers is the de-facto standard for encoding and transmitting any structured information in a compact, platform-independent way. TomTom uses protocol buffers (version 2) format for the output payload. After defining the data structure an encoder and a decoder can be generated for integration into C++, Java and several other languages. Also see http://code.google.com/p/protobuf or https://protobuf.dev for more information.

Important: Protocol buffers schema

Our output type uses the proprietary TomTom protocol buffers message types. The data structure of the protocol buffers output is defined in the schema file ProtobufTrafficFlow_v12.proto. TomTom supports schema version 11 and above.

All fields are marked as optional, as recommended by Google, but the output always contains flow information (including a location).

The following table contains a brief description of the supported message types used in the data structure. More detailed information about the individual message fields can be found in the following sections: some fields are filled in by default, other fields require a specific feature to be enabled with the product.

Location referencing

OpenLR

Geographical representation of the road segments is an important part of the payload. The following geographical representations that are supported:

• OpenLR location referencing,
• Identifier-based location referencing based on OSM way IDs, and
• Identifier-based location referencing based on GERS IDs.

OpenLR is a dynamic location referencing method that allows referencing of any road on the complete digital map. Because of its flexibility, it is possible to describe traffic events on high-level and lower-level road classes. The method is available free of charge. The service uses binary format version 3, as described in the OpenLR whitepaper. The whitepaper, software developer kit, and open source reference implementations are available for download from the OpenLR website. TomTom offers support for third parties to implement and test their own implementations.

1location {
2  openlr: "\v\254\320.!\367\n\033l\a\000Z\376\223\033\000"
3  lengthInMeters: 425
4}

Identifier-based location referencing using OSM way IDs

Identifier-based location referencing OSM way IDs (hereafter called 'IDLR-OSM') is offered as an alternative method of location referencing besides OpenLR and Identifier-based location referencing using GERS IDs.

1. To obtain OSM way IDs from the feed, you must request them using the URL parameter flowType=ff. A detailed explanation of how to use this parameter can be found in the section on Request Parameters.
2. Please note that OSM way IDs are static data. They should only be re-requested as part of the flowType=ff feed (as mentioned in the first point) when there has been a change to the ff feed.
3. You can use the OpenLR codes to link messages from the nff feed to the corresponding messages in the ff feed, allowing you to identify the GERS IDs that were previously downloaded with the ff feed.

The following example shows a trafficFlowWithPredictionPerSection message with an IDLR-OSM in the segmentIds field indicated by type: OSM_WAY_ID that is composed of six OSM way IDs. All IDs use the forward direction, the first ID uses a start-offset, the second through fifth IDs have no offsets, and the sixth ID uses an end-offset. The affected location is the concatenation of all IDs minus the offset information.

1trafficFlowWithPredictionPerSection {
2  location {
3    openlr: "\v\211\302\310.P\211\033n\36418\324\253\033r\344\360I\324\036\033m\350>W\331\341\033l\3572Y\333t\033y\377\344"
4    lengthInMeters: 28533
5    segmentIds {
6      type: OSM_WAY_ID
7      segmentId {
8        id: 230910249
9        backwards: false
10        startOffsetInMeters: 3031
11      }
12      segmentId {
13        id: 631550315
14        backwards: false
15      }
Show hidden lines
28      segmentId {
29        id: 406702547
30        backwards: false
31        endOffsetInMeters: 11317
32      }
33    }
34  }
35  [...]
36}

Identifier-based location referencing using GERS IDs

Identifier-based location referencing Global Entity Reference System (hereafter called 'IDLR-GERS') is offered as an alternative method of location referencing besides OpenLR and IDLR-OSM.

1. To obtain GERS IDs from the feed, you must request them using the URL parameter flowType=ff. A detailed explanation of how to use this parameter can be found in the section on Request Parameters.
2. Please note that GERS IDs are static data. They should only be re-requested as part of the flowType=ff feed (as mentioned in the first point) when there has been a change to the ff feed.
3. You can use the OpenLR codes to link messages from the nff feed to the corresponding messages in the ff feed, allowing you to identify the GERS IDs that were previously downloaded with the ff feed.

The following example shows a trafficFlowWithPredictionPerSection message with an IDLR-GERS in the segmentIds field indicated by type: GERS_ID that is composed of five GERS IDs. All IDs use the backwards direction, the first ID uses a start-offset, the second through fourth IDs have no offsets, and the fifth ID uses an end-offset. The affected location is the concatenation of all IDs minus the offset information.

1trafficFlowWithPredictionPerSection {
2  location {
3    openlr: "\v\004\'|#U\0203\345C\001}\374\216#ffZ"
4    lengthInMeters: 979
5    segmentIds {
6      type: GERS_ID
7      segmentId {
8        id: 319719336117268785
9        backwards: false
10        startOffsetInMeters: 1594
11        idHigh: 604038967628660735
12      }
13      segmentId {
14        id: 319712699939139853
15        backwards: false
16        idHigh: 613046166810001407
17      }
Show hidden lines
28      segmentId {
29        id: 319411736432914706
30        backwards: false
31        endOffsetInMeters: 1398
32        idHigh: 604038967628660735
33      }
34    }
35  }
36  [...]
37}

Note that a 128-bit GERS ID is composed of two 64-bit values represented by the fields id and idHigh. The field idHigh contains the most significant bits, while id contains the least significant bits. The following pseudocode illustrates how these fields should be combined.

gers_id = (idHigh << 64) | id

For more information on how to use GERS IDs, please visit the Overture Maps website.

Available features

Dynamic sectioning

Dynamic sectioning describes the flow segments in smaller sections when conditions vary considerably within a longer road stretch. The Service uses the message type SectionSpeed to report sections. They are ordered by their offset relative to the start of the affected location. This offset is indicated by the startOffsetInMeters field of a SectionSpeed message. A section ends when the subsequent section starts. The last section ends at the end of the affected location indicated by the lengthInMeters field in the Location message.

1trafficFlowWithPredictionPerSection {
2  location {
3    openlr: "\v\254\320.!\367\n\033l\a\000Z\376\223\033\000"
4    lengthInMeters: 425
5  }
6  speedVector {
7    minutesInFuture: 0
8    sectionSpeed {
9      startOffsetInMeters: 0
10      speed {
11        averageSpeedKmph: 2
12        travelTimeSeconds: 86
13        confidence: 81
14        relativeSpeed: 0.067
15        trafficCondition: STATIONARY_TRAFFIC
16      }
17    }
18    sectionSpeed {
19      startOffsetInMeters: 48
20      speed {
21        averageSpeedKmph: 46
22        travelTimeSeconds: 29
23        confidence: 81
24        relativeSpeed: 0.920
25        trafficCondition: FREE_TRAFFIC
26      }
27    }
28  }
29  [...]
30}

Flow prediction

Flow prediction uses the message type TrafficFlowWithPredictionPerSection. The current speed and predictive speeds for 15, 30, 45 minutes in the future are reported with sectioning if applicable.

1trafficFlowWithPredictionPerSection {
2  location {
3    openlr: "\013\003\276\337%BL3\345\t\002\255\000\3273\024"
4    lengthInMeters: 585
5  }
6  speedVector {
7    minutesInFuture: 0
8    sectionSpeed {
9      startOffsetInMeters: 0
10      speed {
11        averageSpeedKmph: 21
12        travelTimeSeconds: 100
13        confidence: 84
14        relativeSpeed: 0.875
15        trafficCondition: FREE_TRAFFIC
16      }
17    }
18  }
19  speedVector {
20    minutesInFuture: 15
21    sectionSpeed {
22      startOffsetInMeters: 0
23      speed {
24        averageSpeedKmph: 20
25        travelTimeSeconds: 105
26        relativeSpeed: 0.838
27        trafficCondition: FREE_TRAFFIC
28      }
29    }
30  }
31  speedVector {
32    minutesInFuture: 30
33    sectionSpeed {
34      startOffsetInMeters: 0
35      speed {
36        averageSpeedKmph: 20
37        travelTimeSeconds: 105
38        relativeSpeed: 0.833
39        trafficCondition: FREE_TRAFFIC
40      }
41    }
42  }
43  speedVector {
44    minutesInFuture: 45
45    sectionSpeed {
46      startOffsetInMeters: 0
47      speed {
48        averageSpeedKmph: 21
49        travelTimeSeconds: 103
50        relativeSpeed: 0.854
51        trafficCondition: FREE_TRAFFIC
52      }
53    }
54  }
55}

HOV Flow

Adds separate speed entries for lanes reserved for high-occupancy vehicles, for now only the current speed for the whole location is available.

The following example shows trafficFlowWithPredictionPerSection message with two speed entries, one for the regular lanes and one for the HOV lane(s).

1trafficFlowWithPredictionPerSection {
2  location {
3    openlr: "\v\251\003-!\331\326\001\f!\002K\371\264\001\037"
4    lengthInMeters: 1939
5  }
6  speedVector {
7    minutesInFuture: 0
8    sectionSpeed {
9      startOffsetInMeters: 0
10      speed {
11        averageSpeedKmph: 76
12        travelTimeSeconds: 92
13        confidence: 100
14      }
15    }
16    sectionSpeed {
17      startOffsetInMeters: 0
18      speed {
19        averageSpeedKmph: 90
20        travelTimeSeconds: 78
21        confidence: 100
22        speedCondition {
23          laneType: HIGH_OCCUPANCY
24        }
25      }
26    }
27  }
28  [...]
29}

Meta information

The MetaInformation message type provides data shared by all traffic flow messages. It contains:

• the creation time (TomTom uses the Epoch Linux Timestamp, which represents the number of seconds since January 1st, 1970 at UTC. For details, check https://www.unixtimestamp.com) and
• the supplier and client information in the SupplierAndClientInfo message.
• the mapVersion field provides the name and version of the map that was used to create the content.

1metaInformation {
2  createTimeUTCSeconds: 1772626830
3  supplierAndClientInfo {
4    clientID: "e28bc9d4-4e05-4918-b662-2562029599565a2f2136"
5    supplierID: "TomTom Traffic Service"
6  }
7  mapVersion: "eur2026.01.140"
8}

The SupplierAndClientInfo is crucial for accessing a flow feed using the recommended free-flow (ff) / non-free-flow (nff) update mechanism as explained in the section Request parameters under the optional URL parameter flowType. The same mechanism needs to be applied for requesting Identifier-based location referencing using OSM way IDs or GERS IDs.

Relative speed

The relative speed to the free-flowing speed is given as a ratio (e.g., 0.250 indicates a current real-time speed that is 25% of free flow speed) in field relativeSpeed in the Speed message.

1trafficFlowWithPredictionPerSection {
2  location {
3    openlr: "\013\265f\361\034J\374\001\0349\363A\006\013\001\014"
4  }
5  speedVector {
6    minutesInFuture: 0
7    sectionSpeed {
8      startOffsetInMeters: 0
9      speed {
10        averageSpeedKmph: 23
11        travelTimeSeconds: 534
12        confidence: 99
13        relativeSpeed: 0.229
14      }
15    }
16  }
17  [...]
18}

Speed message default information

The Speed message contains all speed and travel time related information. It consists of the following default information:

• averageSpeedKmph: The current average speed on the affected location in kilometers per hour.
• travelTimeSeconds: The current average travel time to pass the affected location or free-flow travel time if average speed is 0 km/h (in seconds).
• confidence: A measure of confidence values that rates the reliability of this speed estimate. The quality, amount, and age of live data for the affected location contribute to this score. It scales from 0 (no confidence) to 100 (fully confident about the estimate).

1trafficFlowWithPredictionPerSection {
Show hidden lines
6  speedVector {
7    minutesInFuture: 0
8    sectionSpeed {
9      startOffsetInMeters: 0
10      speed {
11        averageSpeedKmph: 11
12        travelTimeSeconds: 144
13        confidence: 81
14      }
15    }
16  }
17  [...]
18}

Time to usual

Provides the time duration (in minutes) for the average speed (of the entire location) of a flow message to return to the usual speed (speed profile).

1trafficFlowWithPredictionPerSection {
Show hidden lines
47  timeToUsualInMinutes: 26
48}

Traffic condition

Provides a textual traffic condition indicator which provides a categorization of current traffic condition. It can be any value out of seven values (see more details on FAQ about the definition of traffic conditions):

• FREE_TRAFFIC
• HEAVY_TRAFFIC
• SLOW_TRAFFIC
• QUEUING_TRAFFIC
• STATIONARY_TRAFFIC
• CLOSED
• UNKNOWN

1trafficFlowWithPredictionPerSection {
2  location {
3    openlr: "\013\265f\361\034J\374\001\0349\363A\006\013\001\014"
4  }
5  speedVector {
6    minutesInFuture: 0
7    sectionSpeed {
8      startOffsetInMeters: 0
9      speed {
10        averageSpeedKmph: 23
11        travelTimeSeconds: 534
12        confidence: 99
13        trafficCondition: STATIONARY_TRAFFIC
14      }
15    }
16  }
17  [...]
18}