Developer

Enhanced Junction Analytics Batch Data

Service version: v1
Last edit: 2025.04.18
Try 30 Days Free

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 data for all your junctions in a single request, aggregated in 15-minute intervals. Data is returned in Avro format.

Request data

You 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.
  • See the following Request parameters section, which includes tables of required and optional parameters with their expected values. The generic request format is as follows.

HTTPS method: GET

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

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

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.

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] correspond to each hour of day

quarterHour integer

Integer in range [0-3] correspond to each quarter of hour

Request headers

HeaderValue
Content-Typeapplication/avro

Example request

The following is an example curl request:

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

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.

Schema

1{
2  "type": "record",
3  "name": "BatchJunctionTraceStats",
4  "fields": [
5    {
6      "name": "junctionId",
7      "type": "string"
8    },
9    {
10      "name": "approaches",
11      "type": {
12        "type": "array",
13        "items": {
14          "type": "record",
15          "name": "BatchApproachTraces",
16          "fields": [
17            {
18              "name": "approachId",
19              "type": "string"
20            },
21            {
22              "name": "traces",
23              "type": {
24                "type": "array",
25                "items": {
26                  "type": "record",
27                  "name": "BatchApproachTraceStats",
28                  "fields": [
29                    {
30                      "name": "entryTime",
31                      "type": "long"
32                    },
33                    {
34                      "name": "arrivals",
35                      "type": {
36                        "type": "array",
37                        "items": {
38                          "type": "record",
39                          "name": "BatchArrival",
40                          "fields": [
41                            {
42                              "name": "name",
43                              "type": [
44                                "null",
45                                "string"
46                              ]
47                            },
48                            {
49                              "name": "point",
50                              "type": {
51                                "type": "record",
52                                "name": "PointDto",
53                                "fields": [
54                                  {
55                                    "name": "lat",
56                                    "type": "double"
57                                  },
58                                  {
59                                    "name": "lon",
60                                    "type": "double"
61                                  }
62                                ]
63                              }
64                            },
65                            {
66                              "name": "time",
67                              "type": "long"
68                            },
69                            {
70                              "name": "speed",
71                              "type": [
72                                "null",
73                                "int"
74                              ]
75                            }
76                          ]
77                        }
78                      }
79                    },
80                    {
81                      "name": "hasStops",
82                      "type": [
83                        "null",
84                        "boolean"
85                      ]
86                    },
87                    {
88                      "name": "numberOfStops",
89                      "type": [
90                        "null",
91                        "int"
92                      ]
93                    },
94                    {
95                      "name": "exitId",
96                      "type": [
97                        "null",
98                        "string"
99                      ]
100                    },
101                    {
102                      "name": "averageSpeed",
103                      "type": [
104                        "null",
105                        "int"
106                      ]
107                    },
108                    {
109                      "name": "travelTime",
110                      "type": [
111                        "null",
112                        "int"
113                      ]
114                    },
115                    {
116                      "name": "firstStopDistance",
117                      "type": [
118                        "null",
119                        "int"
120                      ]
121                    },
122                    {
123                      "name": "controlStats",
124                      "type": [
125                        "null",
126                        {
127                          "type": "record",
128                          "name": "BatchControlStats",
129                          "fields": [
130                            {
131                              "name": "controlDelay",
132                              "type": [
133                                "null",
134                                "int"
135                              ]
136                            },
137                            {
138                              "name": "approachDelay",
139                              "type": [
140                                "null",
141                                "int"
142                              ]
143                            },
144                            {
145                              "name": "decelerationPointSpeed",
146                              "type": [
147                                "null",
148                                "int"
149                              ]
150                            },
151                            {
152                              "name": "accelerationEndpointSpeed",
153                              "type": [
154                                "null",
155                                "int"
156                              ]
157                            },
158                            {
159                              "name": "entryDistance",
160                              "type": [
161                                "null",
162                                "int"
163                              ]
164                            },
165                            {
166                              "name": "exitDistance",
167                              "type": [
168                                "null",
169                                "int"
170                              ]
171                            },
172                            {
173                              "name": "coveredLength",
174                              "type": [
175                                "null",
176                                "int"
177                              ]
178                            },
179                            {
180                              "name": "numberOfStops",
181                              "type": [
182                                "null",
183                                "int"
184                              ]
185                            },
186                            {
187                              "name": "firstStopDistance",
188                              "type": [
189                                "null",
190                                "int"
191                              ]
192                            }
193                          ]
194                        }
195                      ]
196                    }
197                  ]
198                }
199              }
200            }
201          ]
202        }
203      }
204    }
205  ]
206}

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.

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

  • approachId (integer) The approach ID is unique in the junction context.
  • 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 (integer) The ID of the exit taken by the vehicle from the approach.
    • 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.
    • 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.

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: Junction 5fd9b98a88a13608d7b5d92c is not yet active, no live data available!

401

Unauthorized

403

Forbidden

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

FieldDescription

errorMessage string

Problem description.

Example error response

Response error - JSON
1{
2  "errorMessage": "Batch archive for selected date and time not found."
3}