Service version: v1
Last edit: 2024.01.24

Purpose

The Junction archive is a REST API endpoint designed to fetch a .zip file containing detailed live data for a specified junction. This archive includes snapshots of live data, captured at one-minute intervals.

The Junction archive package is comprised of distinct .csv files, presenting data for each minute in a sequential Excel format. Additionally, the archive provides a separate delivery of the history of junction geometry changes.

Request data

You can can download the Junction archive by sending a GET request, as shown in the following example.

  • 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/archive/{junctionId}/data/flat/daily?key={Your_API_Key}&from={from}&to={to}

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

from


date

Date in format 'yyyy-MM-dd'. The start date of the requested data range.

to


date

Date in format 'yyyy-MM-dd'. The end date of the requested data range.

Request headers

Header

Value

Content-Type

application/octet-stream

Example request

The following is an example curl request:

get
curl command request example
$ curl 'https://api.tomtom.com/junction-analytics/junctions/1/archive/{junctionId}/data/flat/daily?key={Your_API_Key}' -i -X GET \
-H 'Content-Type: application/octet-stream' \

Response data

This response contains .zip file that holds the requested Junction archive data.

Archive .zip file name

The Junction archive .zip file follows a specific naming convention for clarity and organization. The file name structure is as follows:

[junction_id]_[date_from]_[date_to].zip

Here, [junction_id] represents the unique identifier for the junction. The [date_from] and [date_to] segments denote the start and end dates, respectively, for the period covered by the archive. The dates are formatted in the YYYY-MM-DD pattern.

For example:

656dc31ce2c39d2f9c6d29ad_2023-12-01_2023-12-31.zip

Archive .zip file structure

File

Description

readme.pdf


file

The file provides an explanation of the data contained within the .zip file.

csv


directory

Holder of Junction archive data.

csv/definition


directory

Holder of Junction static data. Contains all definitions of a junction during the requested period.

csv/definition/[YYYY_MM_DD_HH_MM_SS]_definition.csv


file

File that holds junction definition in specific time. The date included in the file name corresponds to the date of the junction modification in UTC time.

csv/live-data


directory

Holder of Junction live-data.

csv/live-data/turn_ratios.csv


file

Contains live-data for the turn ratios of a junction during the requested period.

csv/live-data/approaches.csv


file

Contains live data for the approaches of a junction during the requested period.

Archive definition.csv file

In this file you can find all the information about the definition of your junction. Please keep in mind that there will be more files related to this information in case you made any adjustments to the junction geometry in the past.

The information about any changes is indicated in the file name - it starts with the exact time the definition of your junction was changed.

The rows in the .csv file show values for different approaches and exits but also for the junction itself, therefore some values will be duplicated as they are the same for every path (approaches and exits).

The values located in this file are:


Value

Description

junctionID


string

Unique ID of the junction.

junctionName


string

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

id


integer

The approach or the exit ID. Is unique in the junction context.

type


string

It indicates which segmented pathway it's related to, the approach of our junction, or one its exits.< br/> Possible values: APPROACH, EXIT.

name


string

The approach or the exit name.

countryCode


string

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

driveOnLeft


boolean

This is a flag with information about left-hand traffic (LHT) or right-hand traffic (RHT).

trafficLights


boolean

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

roadName


string

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

direction


string

Information about the direction of the traffic flow on a given approach or exit.
One of the values: SOUTH , WEST , EAST , NORTH , CLOCKWISE , COUNTER_CLOCKWISE.

frc


string

Functional Road Class. The lower this number is, the bigger road it's related to (0 being a motorway).
One of the values: 0 , 1 , 2 , 3 , 4 , 5 , 6 , 7.

length


float

Length of the given approach or exit 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. For exits it is always false.

driveable


boolean

Indicates if the road section (the approach or the exit) is drivable.

segmentGeometryWKT


string

Coordinates of the geometry for the whole approach or exit line. This value is defined in the WKT format as a MultiLineString.

openLR


string

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

dataNotAvailable


boolean

Indicates whether live data is available for the approach.

rawJunctionGeometryWKT


string

Contains the junction boundary used in the creation process in the WKT format.

rawJunctionRadius


float

If the junction was created by defining a circle, this column contains information about its radius.

Archive approaches.csv file

This file contains all the historical data for all the approaches you defined during the junction creation process. The data is gathered every 1 minute with a few seconds deviation.

The values located in this file are:

Value

Description

time


datetime

The exact timestamp of saved data.
Example value: 2023-12-31T00:00:19.916543916Z

junctionID


string

Unique ID of the junction.

approachID


integer

The approach or exit ID. It is unique in the junction context.

travelTimeSec


integer

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

freeFlowTravelTime


integer

The time (in seconds) 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 values from historical data.

stops


integer

The average number of stops per vehicle in the last 15 minutes.

queueLengthMeters


integer

This is the queue length in case of a longer-lasting congestion. It might be longer than the length of the approach.

volumePerHour


integer

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

isClosed


boolean

This informs if the approach is currently closed.

stopsHistogram


string

A container that stores histogram data specific to stops.

The data can be interpreted as follows:

  • In the case of 0,3, the data is presented as "numberOfStops": 0, "numberOfVehicles": 3
  • For 0,2;1,1, the data is presented as "numberOfStops": 0, "numberOfVehicles": 2, "numberOfStops": 1, "numberOfVehicles": 1"

Archive turn_ratios.csv file

This file contains information about the turn ratios, where the vehicles are going from the approach (while leaving the intersection).

The values located in this file are:

Value

Description

time


datetime

The exact timestamp of saved data.
Example value: 2023-12-31T00:00:19.916543916Z

junctionID


string

Unique ID of the junction.

approachID


integer

The approach or exit ID. Is unique in the junction context.

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 an exit pass, as occurred during the last thirty minutes.

Errors

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

Error response codes

The following table shows the HTTP error response codes.

Code

Description

401

Unauthorized

403

Forbidden

404

Not Found

  • Junction of id 5fd8da2b84510126b9d18b0d is not found.

Error response field

Field

Description

errorMessage


string

The problem description.

Example error response

The following is an example error response:

Response error message - JSON
1{
2 "errorMessage": "Junction of id 5fd8da2b84510126b9d18b0d not found"
3}