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

Flow Segment Data

 

Service version: 4.0
Last edit: 2019.02.01

On this page

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 layer of the Maps API 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.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the Response.

Request data

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
http(s)://baseURL/traffic/services/versionNumber/flowSegmentData/style/zoom/format?key=*****&point=point
&unit=unit
&thickness=thickness
&openLr=boolean
&jsonp=jsonp

Example

https://api.tomtom.com/traffic/services/4/flowSegmentData/absolute/10/xml?key=*****&point=52.41072,4.84239

curl command

curl -XGET 'https://api.tomtom.com/traffic/services/4/flowSegmentData/absolute/10/xml?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.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter Description
baseURL
string
The base URL for calling TomTom services.
Value: api.tomtom.com
versionNumber
integer
The version of the service to call.
Value: The current value is 4.
style
string
The type of flow data to be displayed on the tile.
Values:

  • absolute
  • relative
  • relative-delay
zoom
integer
The zoom level.
This will affect traffic incident coordinates to present both road sides separately.
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
apiKey
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 EPSG4326 projection.
Value: latitude,longitude
Optional parameters
Parameter 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

Types of traffic flow

Referring to the style parameter, there are various types of traffic flow to use.

  • absolute: This reflects the absolute speed.
  • relative: This is speed relative to free flow, highlighting areas of congestion.
  • relative-delay: These are relative speed values different from the ones for the free-flow. Only highlights areas of congestion.

▲ Return to top

Response data

XML Response body

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

<flowSegmentData xmlns="http://lbs.tomtom.com/services" version="1.0.21-mascoma">
    <frc>FRC2</frc>
    <currentSpeed>41</currentSpeed>
    <freeFlowSpeed>70</freeFlowSpeed>
    <currentTravelTime>153</currentTravelTime>
    <freeFlowTravelTime>90</freeFlowTravelTime>
    <confidence>0.59</confidence>
    <coordinates>
        <coordinate>
            <latitude>52.40476</latitude>
            <longitude>4.844318</longitude>
        </coordinate>
        <coordinate>
            <latitude>52.411312</latitude>
            <longitude>4.8299975</longitude>
        </coordinate>
        <coordinate>
            <latitude>52.415073</latitude>
            <longitude>4.827327</longitude>
        </coordinate>
    </coordinates>
</flowSegmentData>

JSON Response body

{
  "flowSegmentData": {
    "-xmlns": "http://lbs.tomtom.com/services",
    "-version": "1.0.21-mascoma",
    "frc": "FRC2",
    "currentSpeed": "41",
    "freeFlowSpeed": "70",
    "currentTravelTime": "153",
    "freeFlowTravelTime": "90",
    "confidence": "0.59",
    "coordinates": {
      "coordinate": [
        {
          "latitude": "52.40476",
          "longitude": "4.844318"
        },
        {
          "latitude": "52.411312",
          "longitude": "4.8299975"
        },
        {
          "latitude": "52.415073",
          "longitude": "4.827327"
        }
      ]
    }
  }
}

▲ Return to top

Response field structure

The following table describes XML fields that can appear in a Response.

Field Description
<flowSegmentData>
object
Main response element.
The version attribute indicates the software version that generated the response.
<frc>
integer
Functional Road Class. This indicates the road type:

  • 0: Motorway, freeway or other major road
  • 1: Major road, less important than a motorway
  • 2: Other major road
  • 3: Secondary road
  • 4: Local connecting road
  • 5: Local road of high importance
  • 6: 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>
integer
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.

▲ Return to top

HTTP Response codes

Code Meaning and Possible Causes
200 OK
400 Bad request
403 Forbidden: The supplied API Key is not valid for this Request.
500 Internal Server Error
503 Service currently unavailable: The service is currently unavailable.
596 Service Not Found: Unknown version of the service.

▲ Return to top

HTTP Response headers

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

Header Description
Access-Control-Allow-Origin The API allows cross-origin resource sharing (CORS).
Value: *
Cache-Control The API specifies directives for a caching mechanism.
Value: <public, max-age=0>
Content-Length The API contains information about the size of the Response body.
Value: <decimal number>
Content-Type The API indicates the media type of the resource returned.
Value: <application/json>
Date The API contains the date and time at which the message was originated.
Value: <http-date>
Expires The API contains the date after which the Response is considered outdated.
Value: <http-date>

▲ Return to top