Analysis List

Service version: 1

Last edit: 2025.02.25

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.

Request data

HTTPS Method: `GET`

For ease of viewing and identification:

Constants and 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

https://{baseURL}/origindestination/{versionNumber}/analysis?key={Your_API_Key}&page={page}&limit={limit}&name={name}

Example

get

URL request example

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

Request parameters

Required parameters	Description
`baseURL` string	The base URL for calling TomTom services. Value: `api.tomtom.com`
`versionNumber` string	Version of the service to call. Value: The current value is `1`.
`key` string	Authorization key for access to the API. Value: Your valid API Key.

Required parameters

Description

baseURL
string

The base URL for calling TomTom services.

Value: api.tomtom.com

versionNumber
string

Version of the service to call.

Value: The current value is 1.

key
string

Authorization key for access to the API.

Value: Your valid API Key.

Optional parameters	Description
`page` integer	Number of page returned in the response.
`limit` integer	Number of analyses per page.
`name` string	Filter analyses by name containing given value.

Response data

Response Example

Here is an example showing the correct response.

Response body - JSON
1{
"analysisInfos": [
  {
    "id": "1337",
    "name": "Example analysis",
    "owner": "user@example.com",
    "status": "ENDED",
    "currentProgress": 100,
    "creationTime": "2019-07-18T07:39Z",
    "startAnalysisTime": "2019-07-18T07:52Z",
    "startAnalysisTime": "2019-07-18T08:12Z",
    "tripsCounted": 12345,
    "timeDefinition": {
      "dateRanges": [
        {
          "startDate": "2018-12-01",
          "endDate": "2018-12-31",
          "exclusions": ["2018-12-02"]
        }
      ],
      "timeRanges": [
        {
          "startTime": "00:00",
          "endTime": "00:00"
        }
      ],
      "zoneId": "Europe/Warsaw",
      "daysOfWeek": ["WEDNESDAY", "FRIDAY", "MONDAY", "TUESDAY", "THURSDAY"]
    }
  }
],
"numberOfAllAnalyses": 1,
"numberOfPages": 1
34}

Response structure

Field	Description
`analysisInfos` array	List of analysis descriptions.
`numberOfAllAnalyses` integer	Number of all analyses in the response.
`numberOfPages` integer	Number of pages for the provided parameters.

AnalysisInfo structure

Field	Description
`id` integer	Analysis number id.
`name` string	Job name, given for the user’s convenience.
`owner` string	Email of the analysis' owner.
`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 cancelled 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).
`creationTime` dateTime	Job creation time in `YYYY-MM-DDTHH:mm:ss.SSSZ` format.
`timeDefinition` object	Time definition of the analysis.
`timeDefinition.zoneId` string	Time zone as a TZ database name. For example "Europe/Amsterdam" or "UTC"
`timeDefinition.daysOfWeek` string	Days of the week of the analysis. Allowed values: `MONDAY` `TUESDAY` `WEDNESDAY` `THURSDAY` `FRIDAY` `SATURDAY` `SUNDAY`
`timeDefinition.dateRanges` array	List of date ranges of the analysis.
`timeDefinition.timeRanges` array	List of time ranges of the analysis.
`tripsCounted` integer	How many trips were counted. Updates when the analysis is in progress.
`startAnalysisTime` dateTime	Date and time start of the analysis in the format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
`endAnalysisTime` dateTime	Date and time end of the analysis in the format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.

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.
`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.

Response codes

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