Developer

Reports list

Service version: 1

Purpose

Send a GET request to retrieve a list of reports generated by the Area Analytics service.

Request data

HTTPS method: GET

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • 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}/areaanalytics/reports?page={page}&namePattern={namePattern}&pageSize={pageSize}&isArchived={isArchived}&key={Your_API_Key}

Example

get
URL request example
https://api.tomtom.com/areaanalytics/reports?page=1&namePattern=&pageSize=10&isArchived=false&key={Your_API_Key}

Request parameters

Required parameters

Description

baseURL string

The base URL for calling TomTom services.

Value: api.tomtom.com

key string

Authorization key for access to the API.

Value: Your valid API key.

Optional parameters

Description

page integer

Page number for pagination. Default is 1.

namePattern string

Filter reports by name pattern.

pageSize integer

Number of reports per page. Default is 10.

isArchived boolean

Filter reports based on their archived status.

Value: true or false.

statuses List

Filter reports based on their statuses.

Value: NEW, PROCESSING, DONE, FAILED.

Response data

Response example

Here is an example showing the correct response.

Response body - JSON
1{
2  "data": [
3    {
4      "id": "a782dd83-2294-4eb4-acd4-ca5cf6008457",
5      "startDate": "2025-01-01",
6      "endDate": "2025-06-30",
7      "frcs": [0, 1, 2, 3, 4, 5],
8      "hours": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
9      "name": "2025 H1",
10      "dataTypes": [
11        "NETWORK_LENGTH",
12        "CONGESTION_LEVEL",
13        "FREE_FLOW_SPEED",
14        "TRAVEL_TIME",
15        "SPEED"
16      ],
17      "status": "DONE",
18      "createdAt": "2025-08-22T10:58:33.085769",
19      "price": 181,
20      "archived": false
21    }
22  ],
23  "page": 1,
24  "pageSize": 10,
25  "totalElements": 1,
26  "totalPages": 1
27}

Response structure

The response contains pagination information along with the report data. The following tables describe the fields in the response.

Data structure

Field

Description

id string

Unique identifier for the report.

startDate date

Start date of the report in YYYY-MM-DD format.

endDate date

End date of the report in YYYY-MM-DD format.

frcs array

Functional road classes included in the report.

hours array

List of hours included in the report.

name string

Name for the report.

dataTypes array

Data types included in the report. Possible values:

  • NETWORK_LENGTH
  • CONGESTION_LEVEL
  • FREE_FLOW_SPEED
  • TRAVEL_TIME
  • SPEED

status string

Current status of the report. Allowed values:

  • NEW
  • PROCESSING
  • DONE
  • FAILED

createdAt dateTime

Timestamp when the report was created, in ISO 8601 format.

price long

Token price of the report.

archived boolean

Indicates whether the report is archived.

Pagination structure

Field

Description

page integer

Current page number.

pageSize integer

Number of reports per page.

totalElements long

Total number of reports available.

totalPages integer

Total number of pages available.

Errors

If the supplied parameters are invalid or an internal error occurs, the API returns an error response in the requested format.

Response codes

Code

Meaning & possible causes

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found