Junction archive

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

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.

Request headers

Example request

The following is an example curl request:

$ curl 'https://api.tomtom.com/junction-analytics/junctions/1/archive/{junctionId}/data/flat/daily?key={Your_API_Key}&from=2021-01-01&to=2021-01-03' -i -X GET \
    -H 'Content-Type: application/octet-stream' \

Response data

This response contains a .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

readme.pdf (file) The file provides an explanation of the data contained within the .zip file.

csv (directory) Holder of Junction archive data.

• /definition (directory) Holder of Junction static data. Contains all definitions of a junction during the requested period.
  • /[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.
• /live-data (directory) Holder of Junction live-data.
  • /turn_ratios.csv (file) Contains live-data for the turn ratios of a junction during the requested period.
  • /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:

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. 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 (integer) 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:

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.

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:

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 section shows the HTTP error response codes.

Error response field

Example error response

The following is an example error response:

1{
2  "errorMessage": "Junction of id 5fd8da2b84510126b9d18b0d not found"
3}