Live Speed Restrictions - Protobuf

Purpose

The TomTom Live Speed Restrictions – Intermediate Service – Protobuf endpoint (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.

Scope

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.

Important

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.

HTTPS Method: GET

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:

https://{baseURL}/tsq/drr/{productName}/{key}/content.proto

The following is an example request URL:

https://cert-traffic.tomtom.com/tsq/drr/DEU/{Your_API_Key}/content.proto

The following is an example request cURL:

curl --compressed -XGET 'https://cert-traffic.tomtom.com/tsq/drr/DEU/{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.

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.

All responses will be gzip compressed as it significantly reduces the payload size. The use of the HTTP header Accept-Encoding is not necessary. For more information see our page about Gzip compression.

Response data

Response codes

Response example

If you make the following request:

https://cert-traffic.tomtom.com/tsq/drr/DEU/{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
13}
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 {
29      type: VARIABLE_MESSAGE_SIGN
30      speedLimitValue: 80
31      unit: KILOMETRES_PER_HOUR
32      lengthInMeters: 445
33      coordinate {
34        longitudeInDegrees: 4.83437
35        latitudeInDegrees: 52.3379
36      }
37      lastConfirmationTimestampInEpochSeconds: 1681748245
38    }
39    speedLimitSegment {
40      type: VARIABLE_MESSAGE_SIGN
41      speedLimitValue: 60
42      unit: KILOMETRES_PER_HOUR
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  }
53}
54[…]

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 http://code.google.com/p/protobuf or https://developers.google.com/protocol-buffers 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 Schema-LiveSpeedRestrictions_v1.zip. 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.

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

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.