Traffic area analytics

trafficAreaAnalytics runs a historical traffic report for a polygon or multi-polygon region. Give it the region, a date range or a list of dates, and the metrics you want. One call returns the aggregates, their time series and per-tile values, without polling. The Node.js area analytics example prints a week of speed and congestion for Amsterdam.

Introduction

• Any region, from a neighbourhood to a country, as a GeoJSON Polygon or MultiPolygon.
• Any period, as a continuous range that ends up to 31 days after it starts, or a list of separate days.
• Several metrics in one call: speed, free-flow speed, congestion level, travel time and network length.
• Aggregates for the whole period, time series from hourly to yearly, and per-tile values that the Traffic Area Analytics Module draws as grids or a heatmap.
• For planners measuring an infrastructure or policy change, consultants benchmarking areas, analysts and researchers reporting on mobility.

Core concepts

You describe a report with:

• geometry - The region, one per call, as a GeoJSON Polygon or MultiPolygon.
• A date selection, one of:
  • startDate and optional endDate - A continuous range.
  • days - A list of dates, consecutive or not.
• metrics - The metrics to compute, or 'all'.
• functionalRoadClasses - The road classes to include, or 'all'.
• hours - The hours of the day in UTC (0–23) to include, or 'all'.

Basic usage

Traffic Area Analytics is a TomTom MOVE Portal product, so it takes a MOVE Portal API key, not the Maps API key the rest of the SDK uses. Keep your Maps key in TomTomConfig and pass the MOVE Portal key per call (per-call overrides):

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2
import { trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';
3

4
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' }); // Maps API key, for everything else
5

6
const result = await trafficAreaAnalytics({
7
    apiKey: 'YOUR_MOVE_PORTAL_KEY', // this service only
8
    startDate: '2024-08-06',        // YYYY-MM-DD string or Date
9
    endDate: '2024-08-12',          // optional: defaults to three days ago
10
    metrics: ['speed', 'congestionLevel'],
11
    functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD'],
12
    hours: [5, 6, 7, 15, 16],       // UTC: Amsterdam's rush hours in summer time (UTC+2)
13
    geometry: {
14
        type: 'Polygon',
15
        coordinates: [
16
            [[4.896128, 52.382402], [4.875701, 52.368459], [4.923611, 52.36341], [4.896128, 52.382402]],
17
        ],
18
    },
19
});
20

21
const region = result.features[0];
22
console.log(region.properties.baseData.speed);           // km/h
23
console.log(region.properties.baseData.congestionLevel); // %

If this service returns 401 or 403, the call usually went out with your Maps API key.

Available metrics

areaAnalyticsMetricKeys lists them:

Parameters

Date selection

Give either startDate, with an optional endDate, or days. Both take Date objects or 'YYYY-MM-DD' strings, read as UTC calendar days.

Continuous range (startDate / endDate)

• endDate must be 1 to 31 days after startDate, so equal dates fail validation.
• The latest date the API accepts is two days ago, but it publishes a day 24 to 48 hours after it ends. By default, endDate is three days ago, the latest date that always has data.

1
// The last week with data: endDate defaults to three days ago
2
const startDate = new Date();
3
startDate.setUTCDate(startDate.getUTCDate() - 9);
4
const lastWeek = await trafficAreaAnalytics({ startDate, /* ... */ });
5

6
const firstWeekOfAugust = await trafficAreaAnalytics({ startDate: '2024-08-01', endDate: '2024-08-07', /* ... */ });

Specific dates (days)

All days must be two days ago or earlier.

1
// Every Monday of August 2024
2
const result = await trafficAreaAnalytics({
3
    days: ['2024-08-05', '2024-08-12', '2024-08-19', '2024-08-26'],
4
    metrics: ['speed', 'congestionLevel'],
5
    functionalRoadClasses: 'all',
6
    hours: [7, 8, 9, 17, 18],
7
    geometry: { /* ... */ },
8
});

Functional road classes

functionalRoadClasses selects the road classes, or 'all'. The importable functionalRoadClasses catalogue lists them, most important first:

Region geometry

geometry takes one GeoJSON Polygon or MultiPolygon, in [longitude, latitude] order. Each ring must be closed, with equal first and last positions:

1
const geometry = {
2
    type: 'MultiPolygon',
3
    coordinates: [
4
        [[[4.89, 52.37], [4.91, 52.37], [4.91, 52.39], [4.89, 52.39], [4.89, 52.37]]],
5
        [[[4.95, 52.40], [4.97, 52.40], [4.97, 52.42], [4.95, 52.42], [4.95, 52.40]]],
6
    ],
7
};

A city’s boundary comes from geocodeOne and geometryData:

1
import { geocodeOne, geometryData, trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';
2

3
const place = await geocodeOne('Amsterdam, Netherlands');
4
const boundaries = await geometryData({ geometries: [place] });
5

6
const result = await trafficAreaAnalytics({
7
    startDate: '2024-08-06',
8
    endDate: '2024-08-12',
9
    metrics: ['speed', 'congestionLevel'],
10
    functionalRoadClasses: 'all',
11
    hours: [7, 8, 9, 17, 18],
12
    geometry: boundaries.features[0].geometry,
13
});

Set name to name the report. Otherwise, the SDK names it.

Response structure

The result is a TrafficAreaAnalytics FeatureCollection with one feature, the submitted region.

Top-level properties

1
const { startDate, endDate, metrics, frcs, ranges } = result.properties;

• startDate and endDate are the first and last analysed days, as Dates at midnight UTC.
• frcs holds the road classes as the API’s numeric indices, 0 (MOTORWAY) to 8 (OTHER_ROAD).
• ranges holds each metric’s minimum and maximum over the tiles, such as ranges.congestionLevel.

Feature properties

1
const region = result.features[0];
2
const { baseData, timedData, tiledData, anomalies } = region.properties;

Base data

baseData aggregates each requested metric over the whole period. Metrics you didn’t request are absent:

1
const { speed, freeFlowSpeed, congestionLevel, travelTime, networkLength } = region.properties.baseData;

Timed data

timedData breaks the metrics down by granularity. Each has its own entry type, with the metric fields of baseData and its time identifiers always set:

1
const { daily, hourly, average } = region.properties.timedData;
2

3
daily?.forEach((entry) => {
4
    console.log(entry.date.toISOString().slice(0, 10), entry.speed, entry.congestionLevel);
5
});
6

7
// hourly spans every day of the range, so read the day with the hour
8
hourly?.forEach((entry) => {
9
    console.log(`${entry.date.toISOString().slice(0, 10)} ${entry.hour}:00: ${entry.speed} km/h`);
10
});
11

12
average?.forEach((entry) => {
13
    console.log(`Day ${entry.day}, ${entry.hour}:00: ${entry.congestionLevel}%`);
14
});

• Which granularities come back depends on the date range and the hours.
• Every time identifier is in UTC, like hours.
• average holds one entry per day of the week and hour with data, Monday first. A range shorter than a week, or an hours filter, gives fewer than 168. Read day and hour, not the index.
• A weekly entry’s year is the ISO 8601 year its week counts in. The week from Monday, December 30, 2024, is week 1 of 2025.

Tiled data

tiledData holds per-tile values, if the response has them. Each tile has its tileCentre ([longitude, latitude]) and the requested metrics, where networkLength is the road length within that tile.

1
region.properties.tiledData?.tiles.forEach((tile) => {
2
    const [lon, lat] = tile.tileCentre;
3
    console.log(`Tile at [${lon}, ${lat}]: congestion=${tile.congestionLevel}%`);
4
});

To draw them, pass the whole response to the Traffic Area Analytics Module.

The values are per tile, not per road segment. For speeds per segment, call TomTom MOVE’s Traffic Stats API directly with your MOVE Portal key. The SDK doesn’t wrap it.

Anomalies

anomalies maps a metric to its anomalies. Each anomaly is a run of UTC hours, labelled with the public holidays it overlaps. It is currently always empty, because the service detects anomalies only over 35 days or more, beyond a request’s 31-day limit.

1
const speedAnomalies = region.properties.anomalies?.speed ?? [];
2
speedAnomalies.forEach((anomaly) => {
3
    console.log(anomaly.startDate, anomaly.endDate, anomaly.labels);
4
});

Error handling

A failed call rejects with an SDKError whose code says what went wrong. If the API answered with an error, it is an SDKServiceError, which also carries the HTTP status. A request breaking the date rules rejects before it is sent (Error handling).

API reference

• trafficAreaAnalytics
• TrafficAreaAnalyticsParams – Request parameters
• TrafficAreaAnalytics – Response type
• Area Analytics API – API documentation

Related guides and examples

Related examples

• Traffic area analytics NodeJS – Server-side analytics for a geocoded city
• Traffic area analytics – The response drawn as extruded hexagons

Related guides

• Traffic area analytics module – Draw the response on a map
• Traffic incident details – Live incidents of an area
• Geometry data – A place’s boundary, for the region