Developer

Flow Segment Data

Service version: 4
Last edit: 2022.08.15

Purpose

This service provides information about the speeds and travel times of the road fragment closest to the given coordinates. It is designed to work alongside the Flow Tiles to support clickable flow data visualizations. With this API, the client side can connect any place in the map with flow data on the closest road and present it to the user.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Request data

HTTPS method: GET

  • 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 these values. The generic URL format is as follows.

URL format

get
Request URL
https://{baseURL}/traffic/services/{versionNumber}/flowSegmentData/{style}/{zoom}/{format}?key={Your_API_Key}&point={point}&unit={unit}&thickness={thickness}&openLr={boolean}&jsonp={jsonp}

Example

get
Example
https://api.tomtom.com/traffic/services/4/flowSegmentData/absolute/10/xml?key={Your_API_Key}&point=52.41072,4.84239

curl command format

get
curl command
curl 'https:/api.tomtom.com/traffic/services/4/flowSegmentData/absolute/10/xml?key={Your_API_Key}&point=52.41072,4.84239'

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • Optional parameters may be used.

Required parameters

Description

baseURL
string

The base URL for calling TomTom services.
Values:

versionNumber
string

The version of the service to call.
Value: The current value is 4.

style
string

The style used with Raster Flow Tiles and Vector Flow Tiles. This has an effect on the coordinates in the response.
Values:

  • absolute

  • relative

  • relative0

  • relative0-dark

  • relative-delay

  • reduced-sensitivity

zoom
integer

The zoom level.
This has an effect on the following items:

  • Traffic flow coordinates: There may be a slight deviation between the provided coordinates on different zoom levels.

  • Visibility of the particular road: Roads of lower importance are only visible on zoom levels with a higher value.

When Flow Segment data is used together with the Traffic Flow service, the zoom should be the same in both calls.
Values: 0..22

format
string

The content type of the response structure. If the content type is jsonp, a callback method can be specified at the end of the service call.
Values:

  • xml

  • json

  • jsonp

key
string

The authorization key for access to the API.
Value: Your valid API Key.

point
float

The coordinates of the point close to the road segment. They must be comma-separated and calculated using EPSG:4326 projection (also known as WGS84 ).
Value: latitude,longitude

Optional parameters

Description

unit
string

The unit of speed.
Default value: kmph (kilometers per hour)
Other value: mph (miles per hour)

thickness
integer

The segment width multiplier.
Default value: 10
Other values: 1..20

openLr
boolean

Specifies if the response should include OpenLR code.
Default value: false
Other value: true

jsonp
string

Specifies the callback method. Only used where the contentType parameter value is jsonp.
Value: jsonp

Request headers

The following data table lists HTTP request headers of particular interest to clients of the Flow Segment Data API endpoint. Note: There are no required headers in this endpoint.

Optional headers

Description

Accept-Encoding

Contains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip

Tracking-ID

Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'. An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: <string>

Response data

Successful response

The Flow Segment Data API endpoint for a valid single request returns a response in XML or JSON format.

XML response body example

An XSD schema is available for download. The XML response of the preceding sample request would look like this:

Response body - XML
1<flowSegmentData xmlns="http://lbs.tomtom.com/services" version="traffic-service 2.0.004">
2  <frc>FRC2</frc>
3  <currentSpeed>41</currentSpeed>
4  <freeFlowSpeed>70</freeFlowSpeed>
5  <currentTravelTime>153</currentTravelTime>
6  <freeFlowTravelTime>90</freeFlowTravelTime>
7  <confidence>0.59</confidence>
8  <roadClosure>true</roadClosure>
9  <coordinates>
10    <coordinate>
11      <latitude>52.40476</latitude>
12      <longitude>4.844318</longitude>
13    </coordinate>
14    <coordinate>
15      <latitude>52.411312</latitude>
16      <longitude>4.8299975</longitude>
17    </coordinate>
18    <coordinate>
19      <latitude>52.415073</latitude>
20      <longitude>4.827327</longitude>
21    </coordinate>
22  </coordinates>
23</flowSegmentData>
Response body - JSON
1{
2  "flowSegmentData": {
3    "-xmlns": "http://lbs.tomtom.com/services",
4    "-version": "traffic-service 2.0.004",
5    "frc": "FRC2",
6    "currentSpeed": 41,
7    "freeFlowSpeed": 70,
8    "currentTravelTime": 153,
9    "freeFlowTravelTime": 90,
10    "confidence": 0.59,
11    "roadClosure": true,
12    "coordinates": {
13      "coordinate": [
14        {
15          "latitude": 52.40476,
16          "longitude": 4.844318
17        },
18        {
19          "latitude": 52.411312,
20          "longitude": 4.8299975
21        },
22        {
23          "latitude": 52.415073,
24          "longitude": 4.827327
25        }
26      ]
27    }
28  }
29}

Successful response field structure

The following table describes XML or JSON element fields that can appear in a successful response. The types of the fields refer to a JSON response.

Field

Description

<flowSegmentData>
object

Main response element.
The version attribute indicates the software version that generated the response.

<frc>
string

F unctional R oad C lass. This indicates the road type:

  • FRC0 : Motorway, freeway or other major road

  • FRC1 : Major road, less important than a motorway

  • FRC2 : Other major road

  • FRC3 : Secondary road

  • FRC4 : Local connecting road

  • FRC5 : Local road of high importance

  • FRC6 : Local road

<currentSpeed>
integer

The current average speed at the selected point, in the unit requested. This is calculated from the currentTravelTime and the length of the selected segment.

<freeFlowSpeed>
integer

The free flow speed expected under ideal conditions, expressed in the unit requested. This is related to the freeFlowTravelTime.

<currentTravelTime>
integer

Current travel time in seconds based on fused real-time measurements between the defined locations in the specified direction.

<freeFlowTravelTime>
integer

The travel time in seconds which would be expected under ideal free flow conditions.

<confidence>
float

The confidence is a measure of the quality of the provided travel time and speed. A value ranges between 0 and 1 where 1 means full confidence, meaning that the response contains the highest quality data. Lower values indicate the degree that the response may vary from the actual conditions on the road.

<coordinates>
object

This includes the coordinates describing the shape of the segment. Coordinates are shifted from the road depending on the zoom level to support high quality visualization in every scale.

<openlr>
string

The OpenLR code for segment.

<roadClosure>
boolean

This indicates if the road is closed to traffic or not.

Error response

The Flow Segment Data API endpoint for an invalid single request returns a response body in JSON format.

Error response field structure

Field

Description

detailedError
object

Main object of the error response.

code
string

One of a server-defined set of error codes.

message
string

A human-readable description of the error code.
Error response example - JSON
1{
2  "error": "Missing point parameter.",
3  "httpStatusCode": 400,
4  "detailedError": {
5    "code": "INVALID_REQUEST",
6    "message": "Missing point parameter."
7  }
8}

Response codes

Code

Meaning & possible causes

200

OK

400

Bad request

403

Forbidden: The supplied API Key is not valid for this request.

405

Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.

429

Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.

500

Internal Server Error

503

Service currently unavailable: The service is currently unavailable.

596

Service Not Found: Unknown version of the service.

Response headers

The following data table lists HTTP response headers of particular interest to clients of the Flow Segment Data API endpoint.

Header

Description

Access-Control-Allow-Origin

Indicates that cross-origin resource sharing (CORS) is allowed.
Value: *

Allow

Lists the set of supported HTTP methods. The header is sent in case a 405 HTTP response code is returned.
Value: GET, HEAD

Content-Encoding

Indicates which encodings were applied to the response body.
Value: gzip

Cache-Control

Contains directives for a caching mechanism.
Value: <public, max-age=0>

Content-Length

Contains information about the size of the response body.
Value: <decimal number>

Content-Type

Indicates the media type of the resource returned.
Values:

  • <application/json; charset=utf-8>

  • <application/javascript; charset=utf-8>

  • <text/xml; charset=utf-8>

Date

Contains the date and time when the message was originated.
Value: <http-date>

Expires

Contains the date after which the response is considered outdated.
Value: <http-date>

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified in the request, it is replicated in the response. Otherwise, it is generated automatically by the service. For details check RFC 4122. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: <string>