Generate Historical Data Archive

Purpose

The Generate Historical Data Archive endpoint allows you to create an archive generation task for selected junctions within a specified date range.

Request data

You can generate an archive by sending a POST request.

HTTPS method: POST

1
https://api.tomtom.com/junction-analytics/junctions/1/archive/data/tasks/generate?key={Your_API_Key}

POST request body example

1
{
2
  "junctionIds": ["65268ff77cd5d952a185b9b5", "65268ff77cd5d952a185b9b6"],
3
  "startDay": "2024-08-01",
4
  "endDay": "2025-08-01"
5
}

Request parameters

The following table shows the query parameters:

• Required parameters must be used or the call will fail.
• Optional parameters may be used.

Post request body fields

Request headers

Example request

The following is an example curl request to generate an archive for specific junction IDs and date range:

1
$ curl 'https://api.tomtom.com/junction-analytics/junctions/1/archive/data/tasks/generate?key={Your_API_Key}' -i -H 'Content-Type: application/json' -X POST -d '
2
{
3
  "junctionIds": ["65268ff77cd5d952a185b9b5", "65268ff77cd5d952a185b9b6"],
4
  "startDay": "2024-08-01",
5
  "endDay": "2025-08-01"
6
}'

Response data

This response returns the ID of the archive generation task.

The response status tells you whether a task was created:

• 202 Accepted - the archive generation was triggered for at least one of the requested junctions. The body contains the task id and lists the junctions that were and were not triggered.
• 422 Unprocessable Entity - none of the requested junctions could be triggered. No task is created, id is null and isSuccess is false. The body has the same shape as for 202 and lists the reason for every junction.

Response body example

1
{
2
   "id": "65268ff77cd5d952a185b9b7",
3
   "isSuccess": true,
4
   "triggeredJunctions": ["65268ff77cd5d952a185b9b5"],
5
   "notTriggeredJunctions": {
6
     "NO_ARRIVAL_POINTS": ["65268ff77cd5d952a185b9b6"]
7
   }
8
}

Response fields

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

id (string) - Unique identifier for the archive generation task. This ID can be used to check the status of the task later. null when no junction was triggered (422).

isSuccess (boolean) - true when the archive generation was triggered for at least one junction (202), even if other junctions were not triggered. false when no junction was triggered (422).

triggeredJunctions (array) - List of junction IDs for which the archive generation task was successfully triggered.

notTriggeredJunctions (object) - Contains junction IDs that were not triggered, along with the reason for failure. The keys represent the failure reasons, and the values are arrays of junction IDs. Possible keys:

• JUNCTION_NOT_FOUND - the junction does not exist or does not belong to your account.
• NO_ARRIVAL_POINTS - the junction has no arrival points, so no arrival-time data can be generated for it.
• JUNCTION_IN_PROGRESS - another archive generation task of the same archiveType that is still IN_PROGRESS already covers this junction and an overlapping date range.

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.

Error response field

Example error response

The following is an example error response for Unprocessable Entity:

1
{
2
   "id": null,
3
   "isSuccess": false,
4
   "triggeredJunctions": [],
5
   "notTriggeredJunctions": {
6
     "JUNCTION_NOT_FOUND": ["65268ff77cd5d952a185b9b5"],
7
     "NO_ARRIVAL_POINTS": ["65268ff77cd5d952a185b9b6"]
8
   }
9
}