Analysis List

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

Send a GET request to return an analysis list.

The list is paginated and always sorted by creation time, newest first. It covers every analysis type.

Request data

HTTPS Method: `GET`

For ease of viewing and identification:

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.

Format

get

URL request format

1
https://api.tomtom.com/origindestination/1/analysis?key={Your_API_Key}&page={page}&limit={limit}&name={name}&statuses={statuses}&types={types}&analysisVersion={analysisVersion}&favoriteOnly={favoriteOnly}&archivedOnly={archivedOnly}

Example

get

URL request example

1
https://api.tomtom.com/origindestination/1/analysis?page=1&limit=15&key={Your_API_Key}

Request parameters

Required parameters	Description
`key` string	Authorization key for access to the API. Value: Your valid API Key.

Required parameters

Description

key
string

Authorization key for access to the API.

Value: Your valid API Key.

Optional parameters	Description
`page` integer	Number of the page returned in the response. Pages are numbered from 1. Default value: `1`
`limit` integer	Number of analyses per page. Default value: `15`
`name` string	Free text search. An analysis matches when the value is contained in its `name`, or when the value is the exact `id` of the analysis. Matching is case insensitive. Default value: none. Without it the list is not filtered by name.
`statuses` array (of strings)	Comma-separated list of job statuses to return. Default value: all statuses.
`types` array (of strings)	Comma-separated list of analysis types to return. Default value: all types. Possible values: `FLOW_MATRIX` `SELECTED_LINK`
`analysisVersion` integer	Version of the analyses to return. Default value: none. Without it the list is not filtered by version.
`favoriteOnly` boolean	When `true`, only analyses that you marked as favorite are returned. Default value: `false`. Sending the parameter, with either value, also adds the `favorite` field to every analysis in the response.
`archivedOnly` boolean	Selects between archived and non-archived analyses; the two sets are never mixed. When `true`, only archived analyses are returned. Default value: `false`

Response data

Response Example

Here is an example showing the correct response.

Response body - JSON

1
{
2
  "analysisInfos": [
3
    {
4
      "id": "1337",
5
      "name": "Example analysis",
6
      "type": "SELECTED_LINK",
7
      "analysisVersion": 2,
8
      "status": "ENDED",
9
      "currentProgress": 100,
10
      "estimatedDuration": null,
11
      "creationTime": "2026-07-18T07:39Z",
12
      "startAnalysisTime": "2026-07-18T07:52Z",
13
      "endAnalysisTime": "2026-07-18T08:12Z",
14
      "timeDefinition": {
15
        "dateRanges": [
16
          {
17
            "startDate": "2026-06-01",
18
            "endDate": "2026-06-30",
19
            "exclusions": ["2026-06-02"],
20
            "daysOfWeek": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
21
          }
22
        ],
23
        "timeRanges": [
24
          {
25
            "startTime": "00:00",
26
            "endTime": "00:00"
27
          }
28
        ],
29
        "zoneId": "Europe/Warsaw"
30
      }
31
    }
32
  ],
33
  "numberOfAllAnalyses": "1",
34
  "numberOfPages": 1
35
}

Response structure

Field	Description
`analysisInfos` array	List of analysis descriptions for the requested page.
`numberOfAllAnalyses` string	Number of analyses matching the request across all pages, not the number of analyses in this response.
`numberOfPages` integer	Number of pages for the provided parameters.

AnalysisInfo structure

Field	Description
`id` string	Analysis number id.
`name` string	Job name, given for the user’s convenience.
`type` string	Analysis type. One of the following values: `FLOW_MATRIX` `SELECTED_LINK`
`analysisVersion` integer	Version of the analysis. Not returned for analyses created before versioning was introduced.
`status` string	Job status. One of the following values: `WAITING` - analysis is in the queue and waiting for calculation. `RUNNING` - analysis is in progress. `ENDED` - analysis calculation is finished and ready to accept. `FAILED` - analysis calculation failed. `CANCELLED` - analysis was canceled by the user. `ACCEPTED` - analysis was accepted by the user and ready to view. `REJECTED` - analysis was rejected by the user.
`currentProgress` integer	Current value of the job progress (0-100).
`estimatedDuration` integer	Estimated duration of the calculation, in seconds. Produced for Flow Matrix analyses only; `null` when no estimate is available.
`creationTime` datetime	Job creation time in `YYYY-MM-DDTHH:mmZ` format.
`startAnalysisTime` datetime	Date and time start of the analysis in `YYYY-MM-DDTHH:mmZ` format. `null` until the calculation starts.
`endAnalysisTime` datetime	Date and time end of the analysis in `YYYY-MM-DDTHH:mmZ` format. `null` until the calculation stops.
`timeDefinition` object	Time definition of the analysis.
`timeDefinition.zoneId` string	Time zone as a TZ database name. For example `Europe/Amsterdam` or `UTC`.
`timeDefinition.dateRanges` array	List of date ranges of the analysis.
`timeDefinition.timeRanges` array	List of time ranges of the analysis.
`favorite` boolean	Whether the analysis is marked as favorite. Returned only when the request contains the `favoriteOnly` parameter.

Date range format

Field	Description
`startDate` string	Start date of the date range in `YYYY-MM-DD` format.
`endDate` string	End date of the date range in `YYYY-MM-DD` format.
`exclusions` array	List of dates to exclude from a given range in `YYYY-MM-DD` format.
`daysOfWeek` array (of strings)	Days of the week the analysis covers inside this date range. Returned only when the analysis was created with it. Allowed values: `MONDAY` `TUESDAY` `WEDNESDAY` `THURSDAY` `FRIDAY` `SATURDAY` `SUNDAY`
`name` string	Date range name. Given for the user’s convenience. Value: A date range name. For example: `Last working week of January`.

Time range format

Field	Description
`startTime` string	Start time of the time range in `HH:mm` format.
`endTime` string	End time of the time range in `HH:mm` format.

Errors

If there is an error in the supplied parameters or any other internal problem, an error response is generated in the requested format.

A request that matches no analysis is not an error: the response is a 200 with an empty analysisInfos list.

Response codes

Code	Meaning & possible causes
`200`	OK
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found