Junction live data list

Request Access
Service version: v1
Last edit: 2022.08.19

Purpose

Junction definition details is a REST API endpoint that reads dynamic real-time information about a paginated list of junctions. For all of these junctions, it contains the dynamic real-time metrics for each junction approach, including travel time, delay, stops, queue length, and turn ratios for each exit.

Request data

You can obtain the junction live data list by sending a GET request.

  • 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 method: GET

GET
URL request example
https://api.tomtom.com/junction-analytics/junctions/1/live-data?key={Your_API_Key}&page={page}&size={size}

Request parameters

Parameter

Description

key


string

An API Key valid for the requested service.


Value: Your valid API Key.

page


integer

Default value: 0

size


integer

Max: 1000

Request headers

Header

Value

Content-Type

application/json

Example request

The following is an example curl request:

GET
curl command example
$ curl '/junction-analytics/junctions/1/live-data?key={Your_API_Key}&page={page}&size={size}' -i -X GET \
    -H 'Content-Type: application/json' \

Response data

This response returns the junction live data list.

Example response

The following is an example response in JSON format:

Response body - JSON
1{
2  "content": [
3    {
4      "id": "5fb7096db0c41e0cf79e90ce",
5      "approachesLiveData": [
6        {
7          "id": -1497841953,
8          "travelTimeSec": 25,
9          "freeFlowTravelTimeSec": 25,
10          "delaySec": 0,
11          "usualDelaySec": 0,
12          "stops": 0,
13          "queueLengthMeters": 0,
14          "isClosed": true,
15          "turnRatios": [
16            {
17              "exitId": 2032081462,
18              "exitIndex": 2,
19              "ratioPercent": 100,
20              "probesCount": 535
21            }
22          ]
23        },
24        {
25          "id": -1562006886,
26          "travelTimeSec": 85,
27          "freeFlowTravelTimeSec": 85,
28          "delaySec": 0,
29          "usualDelaySec": -1,
30          "stops": 0,
31          "queueLengthMeters": 0,
32          "isClosed": false,
33          "turnRatios": [
34            {
35              "exitId": -351401112,
36              "exitIndex": 0,
37              "ratioPercent": 100,
38              "probesCount": 421
39            }
40          ]
41        }
42      ]
43    },
44    {
45      "id": "5fb70a34b0c41e0cf79e9108",
46      "approachesLiveData": [
47        {
48          "id": -1616034860,
49          "travelTimeSec": 25,
50          "freeFlowTravelTimeSec": 25,
51          "delaySec": 0,
52          "usualDelaySec": -1,
53          "stops": 0,
54          "queueLengthMeters": 0,
55          "isClosed": false,
56          "turnRatios": [
57            {
58              "exitId": -1536796200,
59              "exitIndex": 1,
60              "ratioPercent": 100,
61              "probesCount": 631
62            }
63          ]
64        },
65        {
66          "id": 1910548253,
67          "travelTimeSec": 22,
68          "freeFlowTravelTimeSec": 22,
69          "delaySec": 0,
70          "usualDelaySec": 0,
71          "stops": 0,
72          "queueLengthMeters": 0,
73          "isClosed": true,
74          "turnRatios": [
75            {
76              "exitId": -351401112,
77              "exitIndex": 0,
78              "ratioPercent": 100,
79              "probesCount": 267
80            }
81          ]
82        }
83      ]
84    },
85    {
86      "id": "600012289ffd703722666240",
87      "message": "Junction is not active, no live data available!"
88    }
89  ],
90  "pageable": {
91    "pageNumber": 0,
92    "pageSize": 3,
93    "offset": 0,
94    "paged": true,
95    "unpaged": false
96  },
97  "last": false,
98  "totalElements": 127,
99  "totalPages": 43,
100  "numberOfElements": 3,
101  "first": true,
102  "size": 3,
103  "number": 0,
104  "empty": false
105}

Response fields

The following table describes all the fields that can appear in a response.

Field

Description

content[]


array

This is a list of junctions live data.

content[].id


string

This is the unique ID of a junction.

content[].message


string

This message explains why live data is not available.

content[].approachesLiveData[]


array

The array of an approaches live data, if available.

content[].approachesLiveData[].id


string

The approach id unique in the junction context.

content[].approachesLiveData[].travelTimeSec


integer

This is the time it takes to travel the full approach. It is updated every minute.

content[].approachesLiveData[].freeFlowTravelTimeSec


integer

This is the time it takes to travel the full approach without any delays (usually at nights); it is a fixed value from historical data.

content[].approachesLiveData[].delaySec


integer

Travel time - free flow travel time. This is updated every minute.

content[].approachesLiveData[].usualDelaySec


integer

This is the usual delay expected at this time of day, on this day of the week (derived using historical data). This is calculated using data from speed profiles, and fixed value from historical data.

content[].approachesLiveData[].stops


integer

This is the average number of stops per vehicle. This is updated every minute.

content[].approachesLiveData[].queueLengthMeters


integer

This is the queue length in case of a longer-lasting congestion. This might be longer than the length of the approach. It is updated every minute.

content[].approachesLiveData[].isClosed


boolean

This informs if the approach is currently closed.

content[].approachesLiveData[].volumePerHour *
integer

*Experimental The approximate number of vehicles that have driven through the approach in the last hour.

content[].approachesLiveData[].turnRatios[]


array

This is the list of turn ratios for the approach.

content[].approachesLiveData[].turnRatios[].exitId


string

The exit identifier that this turn ratio points to.

content[].approachesLiveData[].turnRatios[].exitIndex


integer

n/a

content[].approachesLiveData[].turnRatios[].ratioPercent


integer

These ratios are calculated for the last thirty minutes. Only exits where traffic has been observed are included in the output. This is updated every minute.

content[].approachesLiveData[].turnRatios[].probesCount


integer

This is the absolute number of observed probes for this particular approach to exit pass, during last thirty minutes.

pageable


object

This contains information about content page.

pageable.pageNumber


integer

This is the number of the current page.

pageable.pageSize


integer

This is the size of the current page.

pageable.offset


integer

This is the offset of data.

pageable.paged


boolean

This is whether content is paged.

pageable.unpaged


boolean

This is whether content is unpaged.

last


boolean

This is whether the current page is the last page.

totalElements


integer

This is the total number of elements.

totalPages


integer

This is the number of total pages.

numberOfElements


integer

This is the number of elements currently on this page.

first


boolean

This is whether the current page is the first one.

size


integer

This is the size of the page.

number


integer

This is the number of the current page.

empty


boolean

This is whether the current page is empty.

Response errors

An error response is generated if there is an error in the supplied parameters or there is any other internal problem. The system generates the error response in the requested format.

Error response codes

The following table contains the error response codes.

Code

Description

401

Unauthorized

403

Forbidden

Error response fields

Field

Description

errorMessage


string

Problem description.

Example error response

Response error - JSON
1{
2  "errorMessage": "Junction 5fd9b98a88a13608d7b5d92c is not yet active, no live data available!"
3}