Junction live data list

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

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

Request parameters

Request headers

Example request

The following is an example curl request:

$ 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:

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          "stopsHistogram": {
24            "entries": [
25              {
26                "numberOfStops": 0,
27                "numberOfVehicles": 12
28              },
29              {
30                "numberOfStops": 1,
31                "numberOfVehicles": 4
32              }
33            ]
34          }
35        },
36        {
37          "id": -1562006886,
38          "travelTimeSec": 85,
39          "freeFlowTravelTimeSec": 85,
40          "delaySec": 0,
41          "usualDelaySec": -1,
42          "stops": 0,
43          "queueLengthMeters": 0,
44          "isClosed": false,
45          "turnRatios": [
46            {
47              "exitId": -351401112,
48              "exitIndex": 0,
49              "ratioPercent": 100,
50              "probesCount": 421
51            }
52          ],
53          "stopsHistogram": {
54            "entries": [
55              {
56                "numberOfStops": 0,
57                "numberOfVehicles": 5
58              },
59              {
60                "numberOfStops": 1,
61                "numberOfVehicles": 23
62              }
63            ]
64          }
65        }
66      ]
67    },
68    {
69      "id": "5fb70a34b0c41e0cf79e9108",
70      "approachesLiveData": [
71        {
72          "id": -1616034860,
73          "travelTimeSec": 25,
74          "freeFlowTravelTimeSec": 25,
75          "delaySec": 0,
76          "usualDelaySec": -1,
77          "stops": 0,
78          "queueLengthMeters": 0,
79          "isClosed": false,
80          "turnRatios": [
81            {
82              "exitId": -1536796200,
83              "exitIndex": 1,
84              "ratioPercent": 100,
85              "probesCount": 631
86            }
87          ],
88          "stopsHistogram": {
89            "entries": [
90              {
91                "numberOfStops": 0,
92                "numberOfVehicles": 12
93              },
94              {
95                "numberOfStops": 1,
96                "numberOfVehicles": 4
97              }
98            ]
99          }
100        },
101        {
102          "id": 1910548253,
103          "travelTimeSec": 22,
104          "freeFlowTravelTimeSec": 22,
105          "delaySec": 0,
106          "usualDelaySec": 0,
107          "stops": 0,
108          "queueLengthMeters": 0,
109          "isClosed": true,
110          "turnRatios": [
111            {
112              "exitId": -351401112,
113              "exitIndex": 0,
114              "ratioPercent": 100,
115              "probesCount": 267
116            }
117          ],
118          "stopsHistogram": {
119            "entries": [
120              {
121                "numberOfStops": 0,
122                "numberOfVehicles": 4
123              },
124              {
125                "numberOfStops": 1,
126                "numberOfVehicles": 40
127              }
128            ]
129          }
130        }
131      ]
132    },
133    {
134      "id": "600012289ffd703722666240",
135      "message": "Junction is not active, no live data available!"
136    }
137  ],
138  "pageable": {
139    "pageNumber": 0,
140    "pageSize": 3,
141    "offset": 0,
142    "paged": true,
143    "unpaged": false
144  },
145  "last": false,
146  "totalElements": 127,
147  "totalPages": 43,
148  "numberOfElements": 3,
149  "first": true,
150  "size": 3,
151  "number": 0,
152  "empty": false
153}

Response fields

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

content[] (array) This is a list of junctions live data.

• id (string) This is the unique ID of a junction.
• message (string) This message explains why live data is not available.
• approachesLiveData[] (array) The array of an approaches live data, if available.
  • id (string) The approach id unique in the junction context.
  • travelTimeSec (integer) This is the time it takes to travel the full approach. It is updated every minute.
  • 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.
  • delaySec (integer) Travel time - free flow travel time. This is updated every minute.
  • 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 values from historical data.
  • stops (integer) This is the average number of stops per vehicle. This is updated every minute.
  • 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.
  • isClosed (boolean) This informs if the approach is currently closed.
  • volumePerHour (integer) Experimental The approximate number of vehicles that have driven through the approach in the last hour.
  • turnRatios[] (array) This is the list of turn ratios for the approach.
    • exitId (string) The exit identifier that this turn ratio points to.
    • exitIndex (integer) N/A
    • 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.
    • probesCount (integer) This is the absolute number of observed probes for this particular approach to exit pass, during last thirty minutes.

approachesLiveData[] (object) A container that stores histogram data.

• stopsHistogram (object) Stores histogram data specific to stops.
  • entries[] (array) This is a list of histogram stop entries.
    • numberOfStops (integer) This is the number of vehicle stops. It is updated every minute. Non-negative integers.
    • numberOfVehicles (integer) This is the number of vehicles that stopped in numberOfStops. This is updated every minute.Non-negative integers.

pageable (object) This contains information about the content page.

• pageNumber (integer) This is the number of the current page.
• pageSize (integer) This is the size of the current page.
• offset (integer) This is the offset of data.
• paged (boolean) This is if content is paged.
• unpaged (boolean) This is if content is unpaged.

last (boolean) This is if 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 if 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 if 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.

Error response fields

Example error response

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