Flow Segment Data
Service version: 4
Last edit: 2020.12.16
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 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.
- Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- 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=Your_API_Key&point=point&unit=unit&thickness=thickness&openLr=boolean&jsonp=jsonp
Example
https://api.tomtom.com/traffic/services/4/flowSegmentData/absolute/10/xml?key=Your_API_Key&point=52.41072,4.84239
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.
- 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 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:
|
zoom integer |
The zoom level. This has an effect on the following items:
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:
|
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 | |
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 |
HTTP request headers
The following data table lists HTTP request headers of particular interest to clients of the Flow Segment Data API endpoint.
Required headers | |
---|---|
Note: There are no required headers in this endpoint. | |
Optional headers | |
Parameter | 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.
|
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:
<flowSegmentData xmlns="http://lbs.tomtom.com/services" version="traffic-service 2.0.004">
<frc>FRC2</frc>
<currentSpeed>41</currentSpeed>
<freeFlowSpeed>70</freeFlowSpeed>
<currentTravelTime>153</currentTravelTime>
<freeFlowTravelTime>90</freeFlowTravelTime>
<confidence>0.59</confidence>
<roadClosure>true</roadClosure>
<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 example
{
"flowSegmentData": {
"-xmlns": "http://lbs.tomtom.com/services",
"-version": "traffic-service 2.0.004",
"frc": "FRC2",
"currentSpeed": 41,
"freeFlowSpeed": 70,
"currentTravelTime": 153,
"freeFlowTravelTime": 90,
"confidence": 0.59,
"roadClosure": true,
"coordinates": {
"coordinate": [
{
"latitude": 52.40476,
"longitude": 4.844318
},
{
"latitude": 52.411312,
"longitude": 4.8299975
},
{
"latitude": 52.415073,
"longitude": 4.827327
}
]
}
}
}
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 |
Functional Road Class. This indicates the road type:
|
<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.
|
<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
{
"error" : "Missing point parameter.",
"httpStatusCode" : 400,
"detailedError" : {
"code" : "INVALID_REQUEST",
"message" : "Missing point parameter."
}
}
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. |
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. |
HTTP 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. Value:
|
Date |
Contains the date and time at which 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.
|