Junction live data list

Service version: v1
Last edit: 2022.08.05

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={apiKey}&page={page}&size={size}

Request parameters

ParameterDescription
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

HeaderValue
Content-Typeapplication/json

Example request

The following is an example curl request:

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

Response data

This response returns the junction live data list. The following table describes all the fields that can appear in a response.

Response fields

FieldDescription
content[]This is a list of junctions live data.
content[].idThis is the unique ID of a junction.
content[].messageThis message explains why live data is not available.
content[].approachesLiveData[]The array of an approaches live data, if available.
content[].approachesLiveData[].idThe approach id unique in the junction context.
content[].approachesLiveData[].travelTimeSecThis is the time it takes to travel the full approach. It is updated every minute.
content[].approachesLiveData[].freeFlowTravelTimeSecThis 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[].delaySecTravel time - free flow travel time. This is updated every minute.
content[].approachesLiveData[].usualDelaySecThis 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[].stopsThis is the average number of stops per vehicle. This is updated every minute.
content[].approachesLiveData[].queueLengthMetersThis 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[].volumePerHour**Experimental The approximate number of vehicles that have driven through the approach in the last hour.
content[].approachesLiveData[].turnRatios[]This is the list of turn ratios for the approach.
content[].approachesLiveData[].turnRatios[].exitIdThe exit identifier that this turn ratio points to.
content[].approachesLiveData[].turnRatios[].exitIndexn/a
content[].approachesLiveData[].turnRatios[].ratioPercentThese 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[].probesCountThis is the absolute number of observed probes for this particular approach to exit pass, during last thirty minutes.
pageableThis contains information about content page.
pageable.pageNumberThis is the number of the current page.
pageable.pageSizeThis is the size of the current page.
pageable.offsetThis is the offset of data.
pageable.pagedThis is whether content is paged.
pageable.unpagedThis is whether content is unpaged.
lastThis is whether the current page is the last page.
totalElementsThis is the total number of elements.
totalPagesThis is the number of total pages.
numberOfElementsThis is the number of elements currently on this page.
firstThis is whether the current page is the first one.
sizeThis is the size of the page.
numberThis is the number of the current page.
emptyThis is whether the current page is empty.

Example response

The following is an example response in JSON format:

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

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.

HTTP error response codes

The following table contains the error response codes:

CodeDescription
401Unauthorized
403Forbidden

Error response fields

FieldDescription
errorMessageProblem description.

Example error response

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