Developer

Report details

Service version: 1

Purpose

Send a GET request to retrieve detailed information about a specific report 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/{reportID}?key={Your_API_Key}

Example

get
URL request example
https://api.tomtom.com/areaanalytics/reports/a782dd83-2294-4eb4-acd4-ca5cf6008457?key={Your_API_Key}

Request parameters

Required parameters

Description

baseURL string

The base URL for calling TomTom services.

Value: api.tomtom.com

reportID string

The unique identifier for the specific report.

key string

Authorization key for access to the API.

Value: Your valid API key.

Response data

Response example

Here is an example showing the correct response.

Response body - JSON
1{
2    "id": "3b105bbf-5924-432f-afbe-8ea4df2fe01f",
3    "startDate": "2024-08-06",
4    "endDate": "2024-08-06",
5    "frcs": [
6        0,
7        1,
8        2,
9        3,
10        4,
11        5
12    ],
13    "hours": [
14        7,
15        8
16    ],
17    "name": "Amsterdam",
18    "dataTypes": [
19        "NETWORK_LENGTH",
20        "CONGESTION_LEVEL",
21        "FREE_FLOW_SPEED",
22        "TRAVEL_TIME",
23        "SPEED"
24    ],
25    "status": "DONE",
26    "createdAt": "2025-08-26T15:10:26.331897",
27    "price": 1,
28    "archived": false
29}

Response structure

This response will return a structured object containing metadata about the report. The following tables describe the main fields in the response.

Metadata 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

Set of integers representing the FRCS (Functional Road Classes).

hours array

Set of integers representing the hours included in the report.

name string

Name of the report.

dataTypes array

List of data types. Possible values:

  • NETWORK_LENGTH - Sum of all road network segments where data was provided.

  • CONGESTION_LEVEL - Average congestion is calculated by collecting all travel times recorded by TomTom during a given period in a specific area and comparing them with the lowest travel times from when traffic is in a completely fluid state. Congestion is expressed as a percentage, indicating the increase in travel time due to excess traffic. For example, a congestion level of 40 means that, on average, journey times across that area's road network were 40% greater than when traffic is free-flowing.

  • FREE_FLOW_SPEED - Average free-flow travel times are based on static factors in each city, making the score relevant to that city's infrastructure and environment.

  • TRAVEL_TIME - Average travel time per 10 km.

  • SPEED - Average speed on the road network.

status string

Current status of the report. Possible values: NEW, IN_PROGRESS, DONE, FAILED.

createdAt dateTime

Creation date of the report in ISO 8601 format.

price long

Token price associated with the report.

archived boolean

Indicates whether the report is archived.

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