Sorry, you need to enable JavaScript to visit this website.

Junction live data details

Junction live data details

Junction definition details is a REST API endpoint to read 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: junction boundary, its approaches, and exits.

You can obtain Junction live Data details by sending a GET request.

GET https://api.tomtom.com/junction-analytics/junctions/1/<junctionId>/live-data?key=<apiKey>&includeGeometry=<includeGeometry>

Path parameter

ParameterTypeOptionalDefaultDescription

junctionId

String

false

n/a

n/a

Query parameters

ParameterTypeOptionalDefaultDescription

key

String

false

n/a

n/a

includeGeometry

Boolean

true

false

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

Header

HeaderValue

Content-Type

application/json

Example request

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

Response

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

Response fields

FieldTypeOptionalDescription

id

String

false

This is the unique ID of the junction.

approaches[]

Array

false

This is the array of approaches live data.

approaches[].id

Int

false

The unique approach ID in the junction context.

approaches[].travelTimeSec

Int

false

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

approaches[].freeFlowTravelTimeSec

Int

false

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

approaches[].delaySec

Int

false

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

approaches[].usualDelaySec

Int

false

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.

approaches[].stops

Double

false

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

approaches[].queueLengthMeters

Double

false

This is the queue length in case of a longer-lasting congestion. Might be longer than the length of the approach. This is updated every minute.

content[].approaches[].volumePerHour*

Int

false

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

approaches[].turnRatios[]

Array

false

This is a list of turn ratios for the approach.

approaches[].turnRatios[].exitIndex

Int

false

n/a

approaches[].turnRatios[].ratioPercent

Int

false

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.

approaches[].turnRatios[].probesCount

Int

false

This is the absolute number of observed probes for this particular approach to exit pass, as occurred during last thirty minutes.

junctionModel

Object

true

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.id

String

false

This is based on the junction center point.

junctionModel.name

String

false

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

junctionModel.countryCode

String

false

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

junctionModel.driveOnLeft

Boolean

false

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

junctionModel.trafficLight

Boolean

false

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

junctionModel.approaches[]

Array

false

This contains junction approaches.
The minimum number of approaches: 1

junctionModel.approaches[].id

Int

false

The approach ID is unique in the junction context.

junctionModel.approaches[].name

String

false

This is created based on the name and road direction.
Example: "Some Street West Bound".

junctionModel.approaches[].roadName

String

false

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

junctionModel.approaches[].direction

String

false

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

junctionModel.approaches[].frc

Int

false

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

junctionModel.approaches[].oneWayRoad

Boolean

false

It is true, if it is a al road or not a single carriageway road.

junctionModel.approaches[].segmentedGeometry

GeoJson Feature, MultiLineString

false

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

junctionModel.exits[]

Array

false

This contains junction exits.
The minimum number of exits: 1

junctionModel.exits[].name

String

false

This is created based on the name and road direction.
Example: "Typical Street West Bound".

junctionModel.exits[].roadName

String

false

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

junctionModel.exits[].direction

String

false

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

junctionModel.exits[].frc

Int

false

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

junctionModel.exits[].oneWayRoad

Boolean

false

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

junctionModel.exits[].segmentedGeometry

GeoJson Feature, MultiLineString

false

The geometry of a given exit, split by map segments. GeoJson MultiLineString specification

Junction Status

ValueDescription

PREVIEW

The junction is processing, live data is not served.

ACTIVE

The junction is processed, live data is served.

PENDING_UPDATE

The junction is processing after update, live data is not served.

ERROR

Something bad happened (an error occurred).

Example response

The following is an example response:

HTTP/1.1 200 OK
{
    "id": "5fd9bb5a88a13608d7b5d92d",
    "approaches": [
        {
            "id": -1497841953,
            "travelTimeSec": 25,
            "freeFlowTravelTimeSec": 25,
            "delaySec": 0,
            "usualDelaySec": 0,
            "stops": 0.0,
            "queueLengthMeters": 0.0,
            "turnRatios": [
                {
                    "exitIndex": 2,
                    "ratioPercent": 100
                }
            ]
        },
        {
            "id": -531148112,
            "travelTimeSec": 57,
            "freeFlowTravelTimeSec": 57,
            "delaySec": 0,
            "usualDelaySec": 0,
            "stops": 0.0,
            "queueLengthMeters": 0.0,
            "turnRatios": []
        }
    ],
    "junctionModel": {
        "id": "19.4521-51.7766",
        "name": "First Street - Second Street",
        "countryCode": "DEU",
        "driveOnLeft": false,
        "trafficLight": true,
        "approaches": [
            {
                "id": 1397964518,
                "name": "First Street West Bound",
                "roadName": "First Street",
                "direction": "WEST",
                "frc": 7,
                "length": 192.77000427246094,
                "oneWayRoad": false,
                "excluded": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45464,
                            51.77712
                        ],
                        [
                            19.45452,
                            51.77711
                        ],
                        [
                            19.45443,
                            51.77708
                        ]
                     ]
                  ]
                }
            },
            {
                "id": -2036692957,
                "name": "Second Street North Bound",
                "roadName": "Second Street",
                "direction": "NORTH",
                "frc": 4,
                "length": 236.16000366210938,
                "oneWayRoad": true,
                "excluded": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45265,
                            51.77446
                        ],
                        [
                            19.45224,
                            51.77653
                        ],
                        [
                            19.45224,
                            51.77657
                        ]
                     ]
                  ]
                }
            }
        ],
        "exits": [
            {
                "name": "First Street North Bound",
                "roadName": "First Street",
                "direction": "NORTH",
                "frc": 4,
                "oneWayRoad": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45224,
                            51.77657
                        ],
                        [
                            19.45222,
                            51.77665
                        ]
                     ]
                  ]
                }
            },
            {
                "name": "Second Street East Bound",
                "roadName": "Second Street",
                "direction": "EAST",
                "frc": 7,
                "oneWayRoad": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45224,
                            51.77657
                        ],
                        [
                            19.4525,
                            51.77659
                        ]
                     ]
                  ]
                }
            }
        ]
    }
}

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.

CodeNameDescriptionExample error message

400

Bad Request

n/a

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

401

Unauthorized

n/a

n/a

403

Forbidden

n/a

n/a

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

FieldTypeOptionalDescription

errorMessage

String

true

Problem description.

Example error response

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