Enhanced Junction Analytics Batch Data
Purpose
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
| Aspect | Live pipeline | Historical (Archive) pipeline |
|---|---|---|
| Processing frequency | Every 15 minutes | Four times per day (~02:00, 08:00, 14:00, 20:00 UTC) |
| Batch size per cycle | 1 quarter-hour (15 minutes of data) | 24 quarter-hours (6 hours of data) |
| Data latency | ~30 minutes after each 15-minute interval ends | Up to ~6 hours after data collection |
| Data format | Avro (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
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 parameters | Description |
|---|---|
| An API Key valid for the requested service. Value: Your valid API Key. |
| Date in the format of ‘yyyy-MM-dd’. Date for which you want to receive data. |
| Integer in range [0-23] corresponding to each hour of the day. |
| Integer in range [0-3] corresponding to each quarter of the hour. |
| Optional parameters | Description |
|---|---|
| Selects the data pipeline. Allowed values: |
Request headers
| Header | Value |
|---|---|
| Content-Type | application/avro |
Example requests
Historical (Archive) pipeline (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 -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.nullfor 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.nullwhen 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.nullmeans 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: theidreturned by the Junction Archive Data endpoint (POST .../archive/data/tasks/generate).nullmeans 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’sid, and a record carrying a different value ornullwas 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 itsid. 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.controlStatscontrolDelay(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.firstStopDistanceThe 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 specificationspeed(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.nullfor 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.
| Code | Description |
|---|---|
| 400 | Bad Request Example messages:
|
| 401 | Unauthorized |
| 403 | Forbidden |
Error response field
| Field | Description |
|---|---|
| Problem description. |
Example error response
{ "message": "Batch archive for selected date and time not found."}