Developer

Junction live data details

Request Access
Service version: v1
Last edit: 2023.10.25

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={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.

Required parameters

Description

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 parameters

Description

includeGeometry


boolean

If true , the junction geometry is included in the response.


Value: true or false

Request headers

Header

Value

Content-Type

application/json

Example request

The following is an example curl request:

curl command example
$ 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:

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      "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 table describes all of the fields that can appear in a response.

Field

Description

id


string

This is the unique ID of the junction.

approachesLiveData[]


array

This is the array of approaches live data.

approachesLiveData[].id


string

The unique approach ID in the junction context.

approachesLiveData[].travelTimeSec


integer

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

approachesLiveData[].freeFlowTravelTimeSec


integer

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

approachesLiveData[].delaySec


integer

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

approachesLiveData[].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.

approachesLiveData[].stops


integer

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

approachesLiveData[].stopsHistogram


object

A container that stores histogram data specific to stops.

approachesLiveData[].stopsHistogram.entries[]


array

This is a list of histogram stop entries.

approachesLiveData[].stopsHistogram.entries[].numberOfStops


integer

This is the number of vehicle stops. It is updated every minute.


Non-negative integers.

approachesLiveData[].stopsHistogram.entries[].numberOfVehicles


integer

This is the number of vehicles that stopped numberOfStops. This is updated every minute.


Non-negative integers.

approachesLiveData[].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.

approachesLiveData[].isClosed


boolean

This informs if the approach is currently closed.

approachesLiveData[].volumePerHour *
integer

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

approachesLiveData[].turnRatios[]


array

This is a list of turn ratios for the approach.

approachesLiveData[].turnRatios[].exitId


integer

The exit identifier that this turn ratio points to.

approachesLiveData[].turnRatios[].exitIndex


integer

The exit index that this turn ratio points to.

approachesLiveData[].turnRatios[].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.

approachesLiveData[].turnRatios[].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.

junctionModel.name


string

The name of the junction as generated automatically, or provided in the junction definition creation request.

junctionModel.countryCode


string

The three-letter country code as defined in ISO 3166-1 alpha-3 standard.

junctionModel.driveOnLeft


boolean

The flag with information about left-hand traffic (LHT) or right-hand traffic (RHT).

junctionModel.trafficLights


boolean

This is true if there are traffic lights inside the creation area.

junctionModel.approaches[]


array

This contains junction approaches.


The minimum number of approaches: 1

junctionModel.approaches[].id


integer

The approach ID is unique in the junction context.

junctionModel.approaches[].name


string

This is created based on the name and road direction.


Example: "Some Street West Bound".

junctionModel.approaches[].roadName


string

If the road has no name it is "Unnamed road".

junctionModel.approaches[].direction


string

It is one of the following values: SOUTH , WEST , EAST , NORTH , CLOCKWISE , COUNTER_CLOCKWISE.

junctionModel.approaches[].frc


integer

Functional Road Class. It is one of the following values: 0 , 1 , 2 , 3 , 4 , 5 , 6 , 7.

junctionModel.approaches[].length


float

Length of the given approach in meters.

junctionModel.approaches[].oneWayRoad


boolean

It is true , if it is a one-direction road or not a single carriageway road.

junctionModel.approaches[].excluded


boolean

Indicates that live data for the approach is collected.

junctionModel.approaches[].drivable


boolean

Indicates if the road is drivable.

junctionModel.approaches[].segmentedGeometry


object

The geometry of the given approach, split by map segments. See the GeoJSON MultiLineString specification.

junctionModel.approaches[].userPoints


array

Array of user decided points that the geometry routes through. See the GeoJSON Point specification.

junctionModel.approaches[].openlr


string

Geometry of the given approach, encoded into OpenLR format. See the OpenLR specification.

junctionModel.exits[]


array

This contains junction exits.


The minimum number of exits: 1

junctionModel.exits[].id


integer

The exit ID is unique in the junction context.

junctionModel.exits[].name


string

This is created based on the name and road direction.


Example: "Typical Street West Bound".

junctionModel.exits[].roadName


string

If the road has no name, it will be called "Unnamed road".

junctionModel.exits[].direction


string

It is one of the following values: SOUTH , WEST , EAST , NORTH , CLOCKWISE , COUNTER_CLOCKWISE.

junctionModel.exits[].frc


integer

Functional Road Class. It is one of the following values: 0 , 1 , 2 , 3 , 4 , 5 , 6 , 7.

junctionModel.exits[].oneWayRoad


boolean

It is true if it is a one-directional road or not a single carriageway road.

junctionModel.exits[].drivable


boolean

Indicates if the road is drivable.

junctionModel.exits[].segmentedGeometry


object

The geometry of a given exit, split by map segments. See the GeoJSON MultiLineString specification.

junctionModel.exits[].openlr


string

Geometry of the given exit, encoded into OpenLR format. See the OpenLR specification.

Junction Status

The following table shows the junction status.

Value

Description

PREVIEW

Junction is processing, live data is not served.

ACTIVE

Junction is processed, live data is served.

PENDING_UPDATE

Junction is processing after update, live data is not served.

ERROR

Something bad happened (an error occurred).

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.

Code

Description

400

Bad Request


Example: Junction 5fd9b98a88a13608d7b5d92c is not yet active, no live data available!

401

Unauthorized

403

Forbidden

404

Not Found

  • Junction with specified id does not exist or is in ARCHIVED state.

  • Junction of id 5fd8da2b84510126b9d18b0d is not found.

Error response field

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}