Junction live data details

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

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

Request parameters

The following table shows the request parameters.

• Required parameters must be used or the call will fail.
• Optional parameters may be used.

Request headers

Example request

The following is an example curl request:

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

Response data

This response returns junction live data details.

Example response

The following is an example response in JSON format:

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

Response fields

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

id (string) This is the unique ID of the junction.

approachesLiveData[] (array) This is the array of approaches live data.

• id (string) The unique approach ID in the junction context.
• travelTimeSec (integer) The time it takes to travel the full approach. This is updated every minute.
• freeFlowTravelTimeSec (integer) The time it takes to travel the full approach without any delays (usually at nights); the 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 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.
• stops (integer) The average number of stops per vehicle. This is updated every minute.
• stopsHistogram (object) A container that 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.
• queueLengthMeters (integer) This 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.
• isClosed (boolean) This informs if the approach is currently closed.
• volumePerHour (integer) Experimental. The approximated number of vehicles that have driven through the approach in the last hour.
• turnRatios[] (array) This is a list of turn ratios for the approach.
  • exitId (integer) The exit identifier that this turn ratio points to.
  • exitIndex (integer) The exit index that this turn ratio points to.
  • ratioPercent (integer) The 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.
  • probesCount (integer) This is the absolute number of observed probes for this particular approach to exit pass, as occurred during last thirty minutes.

junctionModel (object) Contains the junction geometry and other data. This is not available when the includeGeometry query param is false. This is not available in ERROR status.

• name (string) The name of the junction as generated automatically, or provided in the junction definition creation request.
• countryCode (string) The three-letter country code as defined in ISO 3166-1 alpha-3 standard.
• driveOnLeft (boolean) The flag with information about left-hand traffic (LHT) or right-hand traffic (RHT).
• trafficLights (boolean) This is true if there are traffic lights inside the creation area.
• approaches[] (array) This contains junction approaches. The minimum number of approaches: 1
  • id (integer) The approach ID is unique in the junction context.
  • name (string) This is created based on the name and road direction. Example: "Some Street West Bound".
  • roadName (string) If the road has no name it is "Unnamed road".
  • direction (string) It is one of the following values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE`.
  • frc (integer) Functional Road Class. It is one of the following values: 0, 1, 2, 3, 4, 5, 6, 7.
  • length (float) Length of the given approach in meters.
  • oneWayRoad (boolean) It is true if it is a one-direction road or not a single carriageway road.
  • excluded (boolean) Indicates that live data for the approach is collected.
  • drivable (boolean) Indicates if the road is drivable.
  • segmentedGeometry (object) The geometry of the given approach, split by map segments. See: GeoJSON MultiLineString specification.
  • userPoints (array) Array of user decided points that the geometry routes through. See: GeoJSON Point specification.
  • dataNotAvailable (boolean) Indicates whether live data is available for the approach.
  • openlr (string) Geometry of the given approach, encoded into OpenLR format. See the OpenLR specification.
• exits[] (array) This contains junction exits. The minimum number of exits: 1.
  • id (integer) The exit ID is unique in the junction context.
  • name (string) This is created based on the name and road direction. Example: "Typical Street West Bound".
  • roadName (string) If the road has no name, it will be called "Unnamed road".
  • direction (string) It is one of the following values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.
  • frc (integer) Functional Road Class. It is one of the following values: 0, 1, 2, 3, 4, 5, 6, 7.
  • oneWayRoad (boolean) It is true if it is a one-directional road or not a single carriageway road.
  • drivable (boolean) Indicates if the road is drivable.
  • segmentedGeometry (object) The geometry of a given exit, split by map segments. See the GeoJSON MultiLineString specification.
  • openlr (string) Geometry of the given exit, encoded into OpenLR format. See the OpenLR specification.

Junction Status

The following table shows the junction status.

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.

Error response codes

The following table gives the HTTP error response codes.

Error response field

Example error response

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