Live Speed Restrictions - Intermediate Service - Protobuf

Last edit: 2023.05.15


The TomTom Live Speed Restrictions – Intermediate Service – Protobuf (hereafter called 'Service') is designed for server-to-server integration with navigation and mapping applications.

The Service provides the latest real-time information about speed limits on electronic signs and speed limits in roadwork locations. This data is intended to be used in conjunction with static speed limit information provided by a TomTom map.

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


This document gives basic information on the Service and shows how to configure it to work with your environment. The user is expected to have basic installation knowledge and experience using protocol buffers.

Intended audience

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

Request data

The Service uses RESTful API (Representation State Transfer) technology. Since you only need to use one URL, the service is relatively uncomplicated to use. To make a request, the URL is constructed as shown in the following sections.


To use this service, ensure that all prerequisites are met as described in the section A secure connection or at Authentication for client certificate access.


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 section with the required and optional parameters tables for their values.

The generic request format is as follows:

URL request format

The following is an example request URL:

URL request example{Your_API_Key}/content.proto

Request parameters

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

Required parameters




Base URL for calling the API.




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

Value: e.g., DEU



Authorization key for access to the API.

Value: Your valid API key.

Request headers

As a best practice, TomTom recommends optimizing the information transmission. Through optimization, the client avoids the unnecessary download of identical content and receives more up-to-date information.




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 the HTTP/1.1 standard (RFC2616 section 14.25).
Value: Example: Wed, 21 Oct 2015 07:28:00 GMT


The TomTom Live Speed Restrictions 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. TomTom recommends using this header type as it significantly reduces the payload size.

Value: gzip

Response data

Response example

If you make the following request:

URL request example{Your_API_Key}/content.proto

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

1metaData {
2 creator {
3 uuid {
4 mostSigBits: 5857952150626978573
5 leastSigBits: 9823093239277158625
6 }
7 version: "1"
8 }
9 locationContext {
10 countryCodeISO3: NLD
11 }
12 creationTimeInEpochSeconds: 1681748281
14speedLimitMessage {
15 id {
16 id: "CwNvqiU34gYJDwPAAMoGUCs="
17 }
18 location {
19 type: LINEAR
20 openlr {
21 encoding: OPENLR
22 version: "3"
23 bytes: "\v\003o\252%7\342\006\t\017\003\300\000\312\006P+"
24 }
25 lengthInMeters: 760
26 }
27 speedLimitSequence {
28 speedLimitSegment {
30 speedLimitValue: 80
32 lengthInMeters: 445
33 coordinate {
34 longitudeInDegrees: 4.83437
35 latitudeInDegrees: 52.3379
36 }
37 lastConfirmationTimestampInEpochSeconds: 1681748245
38 }
39 speedLimitSegment {
41 speedLimitValue: 60
43 startPositionInMeters: 445
44 lengthInMeters: 315
45 coordinate {
46 longitudeInDegrees: 4.84054
47 latitudeInDegrees: 52.33765
48 }
49 lastConfirmationTimestampInEpochSeconds: 1681748245
50 }
51 context: TRAFFIC
52 }

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 3) 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 or 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 files contained in the archive TomTom supports schema version 1 and above.

The speed limits are described as segments within the location. The following figure illustrates the relationship between location, segment, offset, and segment information (i.e., the actual speed limit).

Figure 1: Relation between location, segment, and offset.

The following table gives detailed information about the different messages used in the data structure.

Protocol buffers message type



The SpeedLimitsFeed object is the top-level message. It provides meta data and the speed restrictions themselves.


The MetaData message provides data shared by all speed limit messages. It contains the creation time, supplier information, and the country for which the content is created.


The SpeedLimitMessage assigns one or more speed restrictions to a location.


The Location message defines a reference stretch. All SpeedLimitSegment messages are defined by offsets relative to their respective location reference.


The SpeedLimitSequence message holds one or more SpeedLimitSegment messages and information shared by all these segments. This includes the Context, either ROADWORKS for roadworks-related speed restrictions or TRAFFIC for general speed restrictions.


The SpeedLimitSegment represents a continuous, non-overlapping stretch inside the reference location, for which a specific speed restriction is applicable. This message consists of the following:

  • The type of speed restriction sign.

  • The current speed limit value (if applicable) of the affected location.

  • The SpeedInformationUnit which defines the default measurement units.

  • The start position of the segment in meters. This offset is measured from the start of the reference location in the driving direction.

  • The length of the segment. A segment is valid until the next segment on the same location.

  • The approximate coordinate of the speed restriction sign.

  • The timestamp in epoch seconds at which the sign was last confirmed.


The speed information type describes the type of traffic sign. Possible values are:

  • VARIABLE_MESSAGE_SIGN for electronic speed restrictions.

  • TEMPORARY_SPEED_LIMIT_SIGN for static speed restrictions that are installed only temporarily (i.e., in the context of roadworks).

  • END_OF_SPEED_LIMIT for signs that lift all former speed restrictions.

Geographical representation

Geographical representation of the road segments is an important part of the payload. The location reference system used is OpenLR. Since OpenLR prevents interpretation differences, licensing costs, map dependencies, or version dependencies, TomTom recommends using OpenLR.

OpenLR example (here printed using C escape sequences):

1 location {
2 openlr {
3 encoding: OPENLR
4 version: "3"
5 bytes: "\013\004\334L$\335\270\013?\261\003\371!%\013\021"
6 }
7 }


OpenLR is a dynamic location referencing method that allows the 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.