Developer

Analysis List

Request Access
Service version: 1
Last edit: 2024.08.05

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.

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{
2  "analysisInfos": [
3    {
4      "id": "1337",
5      "name": "Example analysis",
6      "owner": "user@example.com",
7      "status": "ENDED",
8      "currentProgress": 100,
9      "creationTime": "2019-07-18T07:39Z",
10      "startAnalysisTime": "2019-07-18T07:52Z",
11      "startAnalysisTime": "2019-07-18T08:12Z",
12      "tripsCounted": 12345,
13      "timeDefinition": {
14        "dateRanges": [
15          {
16            "startDate": "2018-12-01",
17            "endDate": "2018-12-31",
18            "exclusions": ["2018-12-02"]
19          }
20        ],
21        "timeRanges": [
22          {
23            "startTime": "00:00",
24            "endTime": "00:00"
25          }
26        ],
27        "zoneId": "Europe/Warsaw",
28        "daysOfWeek": ["WEDNESDAY", "FRIDAY", "MONDAY", "TUESDAY", "THURSDAY"]
29      }
30    }
31  ],
32  "numberOfAllAnalyses": 1,
33  "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