Junction Analytics

Enhanced Junction Analytics Batch Data

Important Note Explore ready-to-use traffic reports and data visualizations immediately by signing up for a 30-day free trial on the MOVE Portal. Once registered, you’ll receive an API key to start using the Traffic Analytics APIs right away. Alternatively, you may contact our Sales team for a tailored solution.

Purpose

Important Note This endpoint works only if you have been granted access to enhanced features

This endpoint allows you to retrieve batch data for all your junctions in a single request, aggregated in 15-minute intervals. The endpoint uses a single URL and the archiveType query parameter to select between the two available pipelines:

  • Live pipeline (archiveType=LIVE) — delivers near real-time data, processed every 15 minutes with ~30-minute latency.
  • Historical (Archive) pipeline (archiveType=HISTORICAL, default) — delivers consolidated, post-processed data, produced in 6-hour cycles four times per day.

Data pipeline comparison

AspectLive pipelineHistorical (Archive) pipeline
Processing frequencyEvery 15 minutesFour times per day (~02:00, 08:00, 14:00, 20:00 UTC)
Batch size per cycle1 quarter-hour (15 minutes of data)24 quarter-hours (6 hours of data)
Data latency~30 minutes after each 15-minute interval endsUp to ~6 hours after data collection
Data formatAvro (gzip-compressed)Avro (gzip-compressed)

S3 Data Export

Both pipelines can also deliver data directly to your AWS S3 bucket via the S3 Data Export service. For details on setup and delivery, see the S3 Data Export page.

Request data

You can download batch data by sending a GET request. Both pipelines use the same endpoint — the archiveType query parameter controls which pipeline is queried.

  • Constants and parameters enclosed in curly brackets must be replaced with their values.
  • See the following Request parameters section, which includes tables of required and optional parameters with their expected values.

HTTPS method: GET

get
Batch URL request example
https://api.tomtom.com/junction-analytics/junctions/1/archive-batch/data/arrival-times/hourly?key={key}&day={day}&hour={hour}&quarterHour={quarterHour}&archiveType={archiveType}

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 parametersDescription

key string

An API Key valid for the requested service. Value: Your valid API Key.

day date

Date in the format of ‘yyyy-MM-dd’. Date for which you want to receive data.

hour number

Integer in range [0-23] corresponding to each hour of the day.

quarterHour integer

Integer in range [0-3] corresponding to each quarter of the hour.

Optional parametersDescription

archiveType string

Selects the data pipeline. Allowed values: LIVE, HISTORICAL. Defaults to HISTORICAL if not specified.

Request headers

HeaderValue
Content-Typeapplication/avro

Example requests

Historical (Archive) pipeline (default):

curl command example - historical batch (default)
curl -X GET "https://api.tomtom.com/junction-analytics/junctions/1/archive-batch/data/arrival-times/hourly?key=key&day=2023-12-17&hour=1&quarterHour=1"

Live pipeline:

curl command example - live batch
curl -X GET "https://api.tomtom.com/junction-analytics/junctions/1/archive-batch/data/arrival-times/hourly?key=key&day=2023-12-17&hour=1&quarterHour=1&archiveType=LIVE"

Avro response

The response includes the following:

Data Format: The data is returned in Avro file format (binary).

Schema: The Avro schema is included in the response, ensuring you can deserialize the data correctly.

Compression: The response supports gzip compression. You can include the appropriate header in your request to receive a gzipped response.

Redirection: The server responds with a redirection header SEE_OTHER (HTTP status code 303). This header provides the URL of the blob endpoint where the data can be accessed directly. Depending on the HTTP client you are using, redirection might be handled automatically. For example, tools like Postman and web browsers typically follow the redirect without additional configuration. If you are using a custom HTTP client, you may need to handle the redirection explicitly. By including the SEE_OTHER redirection, the server optimizes the process of retrieving large datasets, ensuring efficient access and transfer of data.

The 303 response itself does not contain the Avro data. It carries the signed URL twice: in the Location header and in a JSON body of the form {"url": "<signed URL>"}. The URL is time-limited, so download the file from it right away. The Avro file, with its embedded schema, is what that URL returns.

Both pipelines return data in the same Avro schema.

Schema

{
"type": "record",
"name": "BatchJunctionTraceStats",
"fields": [
{
"name": "junctionId",
"type": "string"
},
{
"name": "externalId",
"type": [
"null",
"string"
]
},
{
"name": "approaches",
"type": {
"type": "array",
"items": {
"type": "record",
"name": "BatchApproachTraces",
"fields": [
{
"name": "approachId",
"type": "string"
},
{
"name": "traces",
"type": {
"type": "array",
"items": {
"type": "record",
"name": "BatchApproachTraceStats",
"fields": [
{
"name": "entryTime",
"type": "long"
},
{
"name": "arrivals",
"type": {
"type": "array",
"items": {
"type": "record",
"name": "BatchArrival",
"fields": [
{
"name": "name",
"type": [
"null",
"string"
]
},
{
"name": "point",
"type": {
"type": "record",
"name": "PointDto",
"fields": [
{
"name": "lat",
"type": "double"
},
{
"name": "lon",
"type": "double"
}
]
}
},
{
"name": "time",
"type": "long"
},
{
"name": "speed",
"type": [
"null",
"int"
]
},
{
"name": "externalId",
"type": [
"null",
"string"
]
}
]
}
}
},
{
"name": "hasStops",
"type": [
"null",
"boolean"
]
},
{
"name": "numberOfStops",
"type": [
"null",
"int"
]
},
{
"name": "exitId",
"type": [
"null",
"string"
]
},
{
"name": "exitExternalId",
"type": [
"null",
"string"
]
},
{
"name": "averageSpeed",
"type": [
"null",
"int"
]
},
{
"name": "travelTime",
"type": [
"null",
"int"
]
},
{
"name": "firstStopDistance",
"type": [
"null",
"int"
]
},
{
"name": "controlStats",
"type": [
"null",
{
"type": "record",
"name": "BatchControlStats",
"fields": [
{
"name": "controlDelay",
"type": [
"null",
"int"
]
},
{
"name": "approachDelay",
"type": [
"null",
"int"
]
},
{
"name": "decelerationPointSpeed",
"type": [
"null",
"int"
]
},
{
"name": "accelerationEndpointSpeed",
"type": [
"null",
"int"
]
},
{
"name": "entryDistance",
"type": [
"null",
"int"
]
},
{
"name": "exitDistance",
"type": [
"null",
"int"
]
},
{
"name": "coveredLength",
"type": [
"null",
"int"
]
},
{
"name": "numberOfStops",
"type": [
"null",
"int"
]
},
{
"name": "firstStopDistance",
"type": [
"null",
"int"
]
}
]
}
]
},
{
"name": "junctionPassId",
"type": [
"null",
"string"
]
},
{
"name": "taskId",
"type": [
"null",
"string"
]
}
]
}
}
},
{
"name": "externalId",
"type": [
"null",
"string"
]
}
]
}
}
}
]
}

Response fields

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

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

externalId (string, nullable) The external identifier of the junction, as set in the junction definition (see External identifiers). null for junctions defined without external identifiers (for example, automatically created ones) and for records produced before external identifiers were introduced.

approaches[] (array) Contains junction approaches. Holder for arrival data per approach:

  • approachId (string) The approach ID is unique in the junction context.
  • externalId (string, nullable) The external identifier of the approach, as set in the junction definition. null for junctions defined without external identifiers (for example, automatically created ones) and for records produced before external identifiers were introduced.
  • traces[] (array) Contains traces in context of approach.
    • hasStops (boolean) Indicates if the vehicle stopped at some point along the approach.
    • numberOfStops (integer) The number of times the vehicle stopped on the approach.
    • firstStopDistance (integer) The distance from the first stop of the vehicle in the queue to the start of the junction in meters.
    • exitId (string) The ID of the exit taken by the vehicle from the approach.
    • exitExternalId (string, nullable) The external identifier of the exit taken by the vehicle, as set in the junction definition. null when none was set or no exit was taken.
    • entryTime (long) Timestamp that trace traversed approach start in UTC time in milliseconds.
    • averageSpeed (integer) The average speed of the vehicle on the approach in kilometers/hour.
    • travelTime (integer) The total time in milliseconds taken by the vehicle to traverse the approach.
    • junctionPassId (string, nullable) A stable, opaque identifier of the vehicle pass through the junction, intended for delta detection across downloads. It identifies the pass in the context of the whole junction, so the same value can appear on records under different approaches — those records describe one physical pass, not duplicates; within a single approach, no two records share an identifier. null means no identifier is available for the record (data processed before this feature was enabled) — treat that as “no delta information”, not as a new pass. See Junction pass identifier for full semantics and privacy properties.
    • taskId (string, nullable) The identifier of the archive generation task whose run added this record or changed its content: the id returned by the Junction Archive Data endpoint (POST .../archive/data/tasks/generate). null means no generation task has touched the record — this is the case for all records produced by the regular daily processing. Use it to see what a given task changed: every record the task added or changed carries the task’s id, and a record carrying a different value or null was not changed by that task. The field holds one value, so a record touched by several tasks carries the id of the most recent one. Treat the value as “this task may have changed the record”, not as a byte-level diff: a small fraction of records can carry the id although their final content equals the previous one. A task that found nothing to change leaves no record with its id. If you receive the data through the S3 data export with completion markers enabled, the same value names the per-run completion marker _COMPLETE_<taskId> written to the day folder once the task’s run has finished for that day, so the marker and the records it touched can be joined by string equality.
    • controlStats
      • controlDelay (integer) The additional time vehicles experience at intersections due to traffic control devices (e.g., signals, stop signs). It includes time lost in deceleration, stopping, queue move-up, and acceleration. Measured in milliseconds per vehicle, it is a key factor in evaluating intersection efficiency and determining Level of Service (LOS).
      • approachDelay (integer) The additional time vehicles experience at approaching an intersection due to traffic control devices (e.g., signals, stop signs). It includes time lost in deceleration, stopping, queue move-up, and acceleration. Measured in milliseconds per vehicle, it is a key factor in evaluating intersection efficiency and determining Level of Service (LOS). Unlike control delay, approach delay does not account for travel within or beyond the intersection.
      • decelerationPointSpeed (integer) The max speed of the vehicle within the control approach.
      • accelerationEndpointSpeed (integer) The max speed of the vehicle within the control exit.
      • entryDistance (integer) Entry distance on control approach in meters.
      • exitDistance (integer) Exit distance on control exit in meters.
      • numberOfStops (integer) The number of times the vehicle stopped on the control approach.
      • firstStopDistance The distance from the first stop of the vehicle in the queue to the start of the junction in meters.
    • arrivals[] (array) Contains arrivals in context of trace.
      • name (string) The descriptive name of the point associated with the arrival.
      • time (long) Timestamp that trace traversed point in UTC time in milliseconds.
      • point (point) Arrival point. A GeoJSON Feature Point that contains the projection point onto the junction approach. GeoJSON Point specification
      • speed (integer) The speed of the vehicle through the arrival point in kilometers/hour.
      • externalId (string, nullable) The external identifier of the arrival point, as set in the junction definition. null for junctions defined without external identifiers (for example, automatically created ones) and for records produced before external identifiers were introduced.

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.

CodeDescription
400

Bad Request Example messages:

  • Batch archive for selected date and time not found.
  • Hour should be in range 0..23. Provided: 24.
  • Quarter hour should be in range 0..3. Provided: 4.
  • Date used in raw archive request 2023-01-01 should be within the past 732 day(s) from now.
401

Unauthorized

403

Forbidden

Error response field

FieldDescription

message string

Problem description.

Example error response

Response error - JSON
{
"message": "Batch archive for selected date and time not found."
}