Junction live data details

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 selected junction. It contains the live metrics for each junction approach including travel time, delay, stops, queue length, and turn ratios for each exit. The response can also, on demand, contain information about the junction model: a junction boundary, its approaches, and exits.

Request data

You can obtain Junction live data details 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/{junctionId}/live-data?key={apiKey}&includeGeometry={includeGeometry}

Request parameters

The following table shows the query parameters.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
Required parametersDescription
junctionId
string
The unique junction id that must be used in the request path.
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
Optional parametersDescription
includeGeometry
boolean
If true, the junction geometry is included in the response.
Value: true or false

Request headers

HeaderValue
Content-Typeapplication/json

Example request

The following is an example curl request:

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

Response data

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

Response fields

FieldDescription
id
This is the unique ID of the junction.
approachesLiveData[]This is the array of approaches live data.
approachesLiveData[].idThe unique approach ID in the junction context.
approachesLiveData[].travelTimeSecThe time it takes to travel the full approach. This is updated every minute.
approachesLiveData[].freeFlowTravelTimeSecThe time it takes to travel the full approach without any delays (usually at nights); the fixed value from historical data.
approachesLiveData[].delaySecTravel time - free-flow travel time. This is updated every minute.
approachesLiveData[].usualDelaySecThis is the usual delay that is expected at this time of day, on this day of the week (as derived using historical data). This is calculated by using data from speed profiles, and fixed value from historical data.
approachesLiveData[].stopsThe average number of stops per vehicle. This is updated every minute.
approachesLiveData[].queueLengthMetersThis is the queue length in case of a longer-lasting congestion. It might be longer than the length of the approach. This is updated every minute.
approachesLiveData[].volumePerHour**Experimental. The approximated number of vehicles that have driven through the approach in the last hour.
approachesLiveData[].turnRatios[]This is a list of turn ratios for the approach.
approachesLiveData[].turnRatios[].exitIdThe exit identifier that this turn ratio points to.
approachesLiveData[].turnRatios[].exitIndexThe exit index that this turn ratio points to.
approachesLiveData[].turnRatios[].ratioPercentThe ratios are calculated for the last thirty (30) minutes. Only exits for which traffic has been observed are included in the output. This is updated every thirty minutes.
approachesLiveData[].turnRatios[].probesCountThis is the absolute number of observed probes for this particular approach to exit pass, as occurred during last thirty minutes.
junctionModelContains the junction geometry and other data. This is not available when the includeGeometry query param is false. This is not available in ERROR status.
junctionModel.nameThe name of the junction as generated automatically, or provided in the junction definition creation request.
junctionModel.countryCodeThe three-letter country code as defined in ISO 3166-1 alpha-3 standard.
junctionModel.driveOnLeftThe flag with information about left-hand traffic (LHT) or right-hand traffic (RHT).
junctionModel.trafficLightsThis is true if there are traffic lights inside the creation area.
junctionModel.approaches[]This contains junction approaches.
The minimum number of approaches: 1
junctionModel.approaches[].idThe approach ID is unique in the junction context.
junctionModel.approaches[].nameThis is created based on the name and road direction.
Example: "Some Street West Bound".
junctionModel.approaches[].roadNameIf the road has no name it is "Unnamed road".
junctionModel.approaches[].directionIt is one of the following values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.
junctionModel.approaches[].frcFunctional Road Class. It is one of the following values: 0, 1, 2, 3, 4, 5, 6, 7.
junctionModel.approaches[].lengthLength of the given approach in meters.
junctionModel.approaches[].oneWayRoadIt is true, if it is a one-direction road or not a single carriageway road.
junctionModel.approaches[].excludedIndicates that live data for the approach is collected.
junctionModel.approaches[].drivableIndicates if the road is drivable.
junctionModel.approaches[].segmentedGeometryThe geometry of the given approach, split by map segments. See the GeoJson MultiLineString specification.
junctionModel.approaches[].userPointsArray of user decided points that the geometry routes through. See the GeoJson Point specification.
junctionModel.approaches[].openlrGeometry of the given approach, encoded into OpenLR format. See the OpenLR specification.
junctionModel.exits[]This contains junction exits.
The minimum number of exits: 1
junctionModel.exits[].idThe exit ID is unique in the junction context.
junctionModel.exits[].nameThis is created based on the name and road direction.
Example: "Typical Street West Bound".
junctionModel.exits[].roadNameIf the road has no name, it will be called "Unnamed road".
junctionModel.exits[].directionIt is one of the following values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.
junctionModel.exits[].frcFunctional Road Class. It is one of the following values: 0, 1, 2, 3, 4, 5, 6, 7.
junctionModel.exits[].oneWayRoadIt is true if it is a one-directional road or not a single carriageway road.
junctionModel.exits[].drivableIndicates if the road is drivable.
junctionModel.exits[].segmentedGeometryThe geometry of a given exit, split by map segments. See the GeoJson MultiLineString specification.
junctionModel.exits[].openlrGeometry of the given exit, encoded into OpenLR format. See the OpenLR specification.

Junction Status

The following table shows the junction status:

ValueDescription
PREVIEWJunction is processing, live data is not served.
ACTIVEJunction is processed, live data is served.
PENDING_UPDATEJunction is processing after update, live data is not served.
ERRORSomething bad happened (an error occurred).

Example response

The following is an example response in JSON format:

Response body - JSON
1{
2 "id": "5fd9bb5a88a13608d7b5d92d",
3 "approachesLiveData": [
4 {
5 "id": -1497841953,
6 "travelTimeSec": 25,
7 "freeFlowTravelTimeSec": 25,
8 "delaySec": 0,
9 "usualDelaySec": 0,
10 "stops": 0,
11 "queueLengthMeters": 0,
12 "turnRatios": [
13 {
14 "exitId": 2032081462,
15 "exitIndex": 2,
16 "ratioPercent": 100,
17 "probesCount": 535
18 }
19 ]
20 },
21 {
22 "id": -531148112,
23 "travelTimeSec": 57,
24 "freeFlowTravelTimeSec": 57,
25 "delaySec": 0,
26 "usualDelaySec": 0,
27 "stops": 0,
28 "queueLengthMeters": 0,
29 "turnRatios": [
30 {
31 "exitId": -351401112,
32 "exitIndex": 2,
33 "ratioPercent": 100,
34 "probesCount": 421
35 }
36 ]
37 }
38 ],
39 "junctionModel": {
40 "name": "First Street - Second Street",
41 "countryCode": "DEU",
42 "driveOnLeft": false,
43 "trafficLights": true,
44 "approaches": [
45 {
46 "id": 1397964518,
47 "name": "First Street West Bound",
48 "roadName": "First Street",
49 "direction": "WEST",
50 "frc": 7,
51 "length": 192.77,
52 "oneWayRoad": false,
53 "excluded": false,
54 "drivable": true,
55 "segmentedGeometry": {
56 "type": "MultiLineString",
57 "coordinates": [
58 [
59 [
60 19.45464,
61 51.77712
62 ],
63 [
64 19.45452,
65 51.77711
66 ],
67 [
68 19.45443,
69 51.77708
70 ]
71 ]
72 ]
73 },
74 "userPoints": [
75 {
76 "type": "Point",
77 "coordinates": [
78 19.45464,
79 51.77712
80 ]
81 },
82 {
83 "type": "Point",
84 "coordinates": [
85 19.45443,
86 51.77708
87 ]
88 }
89 ],
90 "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
91 "dataNotAvailable": false
92 },
93 {
94 "id": -2036692957,
95 "name": "Second Street North Bound",
96 "roadName": "Second Street",
97 "direction": "NORTH",
98 "frc": 4,
99 "length": 236.16,
100 "oneWayRoad": true,
101 "excluded": false,
102 "drivable": true,
103 "segmentedGeometry": {
104 "type": "MultiLineString",
105 "coordinates": [
106 [
107 [
108 19.45265,
109 51.77446
110 ],
111 [
112 19.45224,
113 51.77653
114 ],
115 [
116 19.45224,
117 51.77657
118 ]
119 ]
120 ]
121 },
122 "userPoints": [
123 {
124 "type": "Point",
125 "coordinates": [
126 19.45265,
127 51.77446
128 ]
129 },
130 {
131 "type": "Point",
132 "coordinates": [
133 19.45224,
134 51.77657
135 ]
136 }
137 ],
138 "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
139 "dataNotAvailable": false
140 }
141 ],
142 "exits": [
143 {
144 "id": 2032081462,
145 "name": "First Street North Bound",
146 "roadName": "First Street",
147 "direction": "NORTH",
148 "frc": 4,
149 "oneWayRoad": false,
150 "drivable": true,
151 "segmentedGeometry": {
152 "type": "MultiLineString",
153 "coordinates": [
154 [
155 [
156 19.45224,
157 51.77657
158 ],
159 [
160 19.45222,
161 51.77665
162 ]
163 ]
164 ]
165 },
166 "openlr": "Dw3VGCTJOhJTB/5H/toWSXY="
167 },
168 {
169 "id": -351401112,
170 "name": "Second Street East Bound",
171 "roadName": "Second Street",
172 "direction": "EAST",
173 "frc": 7,
174 "oneWayRoad": false,
175 "drivable": true,
176 "segmentedGeometry": {
177 "type": "MultiLineString",
178 "coordinates": [
179 [
180 [
181 19.45224,
182 51.77657
183 ],
184 [
185 19.4525,
186 51.77659
187 ]
188 ]
189 ]
190 },
191 "openlr": "Ew3VGCTJOhJTB/5H/toWSXY="
192 }
193 ]
194 }
195}

Errors

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

HTTP error response codes

The following table gives the error response codes.

CodeDescription
400Bad Request
Example: Junction 5fd9b98a88a13608d7b5d92c is not yet active, no live data available!
401Unauthorized
403Forbidden
404Not Found
  • Junction with specified id does not exist or is in ARCHIVED state
  • Junction of id 5fd8da2b84510126b9d18b0d is not found.

Error response field

FieldDescription
errorMessageProblem description.

Example error response

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