Developer

Report creation

Service version: 1

Purpose

Create an Area Analytics report by sending a POST request.

Request data

HTTPS method: POST

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

post
URL request format
https://{baseURL}/areaanalytics/reports?key={Your_API_Key}

Example

post
URL request example
https://api.tomtom.com/areaanalytics/reports?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.

Request POST body example

post
POST request body - JSON
1{
2  "name": "Amsterdam",
3  "startDate": "2024-08-06",
4  "endDate": "2024-08-06",
5  "hours": [
6    7,
7    8
8  ],
9  "frcs": [
10    0,
11    1,
12    2,
13    3,
14    4,
15    5
16  ],
17  "dataTypes": [
18    "NETWORK_LENGTH",
19    "CONGESTION_LEVEL",
20    "FREE_FLOW_SPEED",
21    "TRAVEL_TIME",
22    "SPEED"
23  ],
24  "features": [
25    {
26      "type": "Feature",
27      "properties": {
28        "name": "Amsterdam",
29        "timezone": "Europe/Amsterdam"
30      },
31      "geometry": {
32        "coordinates": [
33          [
34            [
35              4.896128,
36              52.382402
37            ],
38            [
39              4.875701,
40              52.368459
41            ],
42            [
43              4.923611,
44              52.36341
45            ],
46            [
47              4.896128,
48              52.382402
49            ]
50          ]
51        ],
52        "type": "Polygon"
53      }
54    }
55  ]
56}

Request POST body fields

Required fields

Description

name
string

Name of the report.

startDate
date

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

endDate
date

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

dataTypes
array

List of data types to analyze.
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.

frcs
array

Set defining the frequency levels to include.
Possible values: 0,1,2,3,4,5,6,7,8

hours
array

Set of integers representing the hours to analyze.
Possible values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23

features
array

List of region definitions.

Required POST headers

Header

Value

Content-Type

application/json

Regions definition format

Regions should be defined as a GeoJSON Feature Object. Each feature can only contain the following types of geometries: Polygon, MultiPolygon. You may define the feature properties called name and timezone for every region. Otherwise, they will be generated automatically.

Response data

This response will return information about the created area analytics report. The following table describes all of the fields that can appear in a response.

Response structure

Field

Description

id
string

Report ID for the created area analytics. Processing is asynchronous. Report ID may be used for fetching response using /results endpoint

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

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found