Lite report aggregation

Service version: 1

Purpose

Create an aggregated data of simple and quick version of the 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 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/lite/aggregated?key={Your_API_Key}&aggregation={aggregation}

Example

post

URL request example

https://api.tomtom.com/areaanalytics/reports/lite/aggregated?key={Your_API_Key}

Request parameters

Required parameters	Description
`baseURL` string	The base URL for calling TomTom services. Value: `api.tomtom.com`
`id` string (uuid)	The unique identifier of the report. Value: A valid UUID format string.
`featureId` string (uuid)	The unique identifier of the feature/region. Value: A valid UUID format string.
`key` string	Authorization key for access to the API. Value: Your valid API key.

Optional parameters	Description
`aggregation` string	The type of time-based aggregation to apply to the results. Possible values: `HOURLY` - Aggregate by hour `DAILY` - Aggregate by day `WEEKLY` - Aggregate by week `MONTHLY` - Aggregate by month `YEARLY` - Aggregate by year `DAY_OF_WEEK` - Aggregate by day of the week `HOUR_OF_DAY` - Aggregate by hour of the day `DAY_HOUR_OF_WEEK` - Aggregate by day and hour of the week
`daysOfWeek` array of integers	Filter results to include only specific days of the week. Value: Array of integers from 1 (Monday) to 7 (Sunday) according to ISO 8601 standard.
`hours` array of integers	Filter results to include only specific hours of the day. Value: Array of integers from 0 to 23.
`excludeDates` array of dates	Exclude specific dates from the aggregation. Value: Array of date strings in ISO format (YYYY-MM-DD).
`excludeAnomalies` boolean	Whether to exclude anomalous data points from the aggregation. Value: `true` or `false`

Request POST body

Same as in Report creation, see Request POST body example.

Request POST body limitations

The request body has the same structure but with the following constraints:

Required fields	Description
`endDate` string	The end date must be within 31 days from `startDate`.
`days` string	If days are provided, the total number of days cannot exceed 31.
`features` array	A list containing only one region definition.

Required POST headers

Header	Value
Content-Type	`application/json`

Region definition format

A region should be defined as a GeoJSON Feature Object. The feature can contain only the following type of geometry: Polygon. You may define the feature properties name and timezone for the region. Otherwise, they will be generated automatically.

Response data

Response format

The response contains aggregated results in JSON format with the structure defined by the AggregatedResponse schema.

Response body example

AggregatedResponse - JSON
1{
"points": [
   {
      "time": "2024-08-01T00:00",
      "v": 22.2,
      "fv": 27.4,
      "c": 23.4,
      "t": 27.0,
      "l": 15.74
   },
   {
      "time": "2024-08-01T01:00",
      "v": 22.2,
      "fv": 27.4,
      "c": 23.4,
      "t": 27.0,
      "l": 15.74
   }
]
20}

Response body fields

Data Key	Description
`time`	Time aggregation level. Possible values: Date-time string in ISO-8601 format (YYYY-MM-DDTHH:MM:SS) Combination of (MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY) and (0,1,...,23) describing particular day and hour of week
`l`	NETWORK_LENGTH - Sum of all road network segments where data was provided.
`c`	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.
`fv`	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.
`t`	TRAVEL_TIME - Average travel time per 10 km.
`v`	SPEED - Average speed on the road network.

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