Traffic Area Analytics

Important note Traffic Area Analytics is unavailable on a Freemium or Pay As You Grow (PAYG) basis. Click the Request Access button above to contact our Sales team.

Traffic Area Analytics runs historical traffic reports for a polygon or multi-polygon region. Provide a GeoJSON Polygon (or MultiPolygon), a date range or specific dates, and the metrics you care about — the trafficAreaAnalytics method synchronously returns aggregated statistics and time-series breakdowns without any polling.

import type { AreaAnalyticsDataType } from '@tomtom-org/maps-sdk/core';
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { geocodeOne, geometryData, trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';
import { API_KEY } from './config';

TomTomConfig.instance.put({ apiKey: API_KEY });

(async () => {
    const geocodedLocation = await geocodeOne('Amsterdam, Netherlands');
    console.log(`Geocoded: ${geocodedLocation.properties.address.freeformAddress}`);

    const boundary = (await geometryData({ geometries: [geocodedLocation] })).features[0];

    const today = new Date();
    const startDate = new Date(today);
    startDate.setUTCDate(startDate.getUTCDate() - 7);

    console.log(`Analysis period: ${startDate.toDateString()} → ${today.toDateString()}`);

    const dataTypes: AreaAnalyticsDataType[] = ['SPEED', 'CONGESTION_LEVEL'];
    const result = await trafficAreaAnalytics({
        startDate,
        dataTypes,
        functionalRoadClasses: [
            'MOTORWAY',
            'MAJOR_ROAD',
            'OTHER_MAJOR_ROAD',
            'SECONDARY_ROAD',
            'LOCAL_CONNECTING_ROAD',
            'LOCAL_ROAD_HIGH_IMPORTANCE',
        ],
        hours: 'all',
        geometry: boundary.geometry,
    });

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

    console.log('\n=== Base Data (full period) ===');
    if (baseData.speed) {
        console.log(`  Average speed:    ${baseData.speed.toFixed(1)} km/h`);
    }
    if (baseData.congestionLevel) {
        console.log(`  Congestion level: ${baseData.congestionLevel.toFixed(1)}%`);
    }

    if (timedData.daily && timedData.daily.length > 0) {
        console.log('\n=== Daily Breakdown ===');
        for (const entry of timedData.daily) {
            const date = entry.date?.toISOString().slice(0, 10) ?? '?';
            const speed = entry.speed?.toFixed(1) ?? 'n/a';
            const congestion = entry.congestionLevel?.toFixed(1) ?? 'n/a';
            console.log(`  ${date}: speed=${speed} km/h, congestion=${congestion}%`);
        }
    }
})();

Introduction

Traffic Area Analytics is TomTom’s custom traffic analytics tool for analyzing congestion patterns and mobility insights across any geographic area and timeframe. Define custom regions at any scale — from a single neighborhood to an entire country — and retrieve detailed historical traffic metrics: congestion levels, speeds, travel times, and road network coverage.

Who Is It For?

Traffic Area Analytics is built for professionals who need reliable, historical traffic data to make decisions:

Government & urban planners — evaluate infrastructure changes, measure the impact of new policies, and make data-driven decisions to improve mobility.
Traffic consultants — validate traffic management solutions and benchmark areas using granular historical data.
Financial analysts — assess investment risk and opportunity related to urban mobility and infrastructure projects.
Media & research — produce accurate, data-backed reporting on transportation trends and the impact of real-world events.

Key Advantages

Custom regions — analyse any shape at any scale by supplying a GeoJSON Polygon or MultiPolygon.
Flexible time selection — use a continuous date range (up to 31 days) or a list of specific, non-consecutive dates.
Multiple metrics in one call — request speed, free-flow speed, congestion level, travel time, and network length together.
No polling — results are returned synchronously in a single API call.
Rich breakdowns — aggregated base data, time-series breakdowns (hourly, daily, monthly), per-tile heatmap data, and anomaly detection.

Core Concepts

Each analysis report is described by:

Region (geometry): a GeoJSON Polygon or MultiPolygon defining the area to analyse.
Date selection — choose one of:
- startDate + endDate: a continuous date range, capped at 31 days.
- days: an explicit list of specific (possibly non-consecutive) dates.
Data types (dataTypes): one or more traffic metrics to compute — see Available Metrics .
Functional road classes (functionalRoadClasses): which road categories to include — see Functional Road Classes . Pass 'all' to include every class.
Hours (hours): which hours of the day (0–23) to include in the analysis, or 'all' to include every hour.

Basic Usage

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' });
5

6
const result = await trafficAreaAnalytics({
7
    startDate: '2024-08-06',   // YYYY-MM-DD string or Date object
8
    endDate: '2024-08-06',     // optional — defaults to today when omitted
9
    dataTypes: ['SPEED', 'CONGESTION_LEVEL'],
10
    functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD', 'LOCAL_CONNECTING_ROAD', 'LOCAL_ROAD_HIGH_IMPORTANCE'],
11
    hours: [7, 8, 9, 17, 18],  // morning and evening rush hours
12
    geometry: {
13
        type: 'Polygon',
14
        coordinates: [
15
            [[4.896128, 52.382402], [4.875701, 52.368459], [4.923611, 52.36341], [4.896128, 52.382402]]
16
        ]
17
    }
18
});
19

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

Available Metrics

`dataTypes` value	Description	Unit
`'SPEED'`	Average speed on the road network	km/h
`'FREE_FLOW_SPEED'`	Average speed under uncongested conditions	km/h
`'CONGESTION_LEVEL'`	Percentage increase in travel time above free-flow	%
`'TRAVEL_TIME'`	Average travel time per 10 km	minutes
`'NETWORK_LENGTH'`	Total length of road segments with data	meters

Parameters

Date Selection

Supply either startDate + endDate or days — these two options are mutually exclusive.

Continuous range (`startDate` / `endDate`)

Both fields accept a JavaScript Date object or an ISO 'YYYY-MM-DD' string. endDate is optional — when omitted it defaults to today. The range must not exceed 31 days:

1
// startDate only — endDate defaults to today
2
const result = await trafficAreaAnalytics({ startDate: '2024-08-01', /* ... */ });
3

4
// Explicit range using YYYY-MM-DD strings
5
const result = await trafficAreaAnalytics({
6
    startDate: '2024-08-01',
7
    endDate: '2024-08-07',
8
    /* ... */
9
});
10

11
// Or using Date objects (computed dynamically)
12
const endDate = new Date();
13
endDate.setUTCHours(0, 0, 0, 0);
14

15
const startDate = new Date(endDate);
16
startDate.setUTCDate(startDate.getUTCDate() - 7);
17

18
const result = await trafficAreaAnalytics({ startDate, endDate, /* ... */ });

Specific dates (`days`)

Use days to analyse a list of individual (possibly non-consecutive) dates. Accepts Date objects or 'YYYY-MM-DD' strings:

1
// All Mondays in August 2024
2
const result = await trafficAreaAnalytics({
3
    days: ['2024-08-05', '2024-08-12', '2024-08-19', '2024-08-26'],
4
    dataTypes: ['SPEED', 'CONGESTION_LEVEL'],
5
    functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD', 'LOCAL_CONNECTING_ROAD', 'LOCAL_ROAD_HIGH_IMPORTANCE'],
6
    hours: [7, 8, 9, 17, 18],
7
    geometry: { /* ... */ }
8
});

Functional Road Classes

functionalRoadClasses selects which road categories are included in the analysis. Pass 'all' to include every class:

Value	Description
`'MOTORWAY'`	Motorways, freeways, and major roads
`'MAJOR_ROAD'`	Major roads, less important than motorways
`'OTHER_MAJOR_ROAD'`	Other major roads connecting neighbouring regions
`'SECONDARY_ROAD'`	Secondary roads linking parts of the same region
`'LOCAL_CONNECTING_ROAD'`	Local roads providing settlement access
`'LOCAL_ROAD_HIGH_IMPORTANCE'`	Local roads of high importance within a settlement
`'LOCAL_ROAD'`	Local roads within settlement sections
`'LOCAL_ROAD_MINOR_IMPORTANCE'`	Local roads of minor importance (dead-ends, alleys)
`'OTHER_ROAD'`	Other roads (paths, cycle routes, pedestrian infrastructure)

Region Geometry

The geometry property accepts a GeoJSON Polygon or MultiPolygon. Coordinates must be in [longitude, latitude] order and rings must be closed (first and last coordinate identical):

1
// Polygon
2
const geometry = {
3
    type: 'Polygon',
4
    coordinates: [
5
        // Coordinates in [longitude, latitude] order — ring must be closed
6
        [[4.89, 52.37], [4.91, 52.37], [4.91, 52.39], [4.89, 52.39], [4.89, 52.37]]
7
    ]
8
};
9

10
// MultiPolygon (e.g. a city boundary with enclaves)
11
const geometry = {
12
    type: 'MultiPolygon',
13
    coordinates: [
14
        [[[4.89, 52.37], [4.91, 52.37], [4.91, 52.39], [4.89, 52.39], [4.89, 52.37]]],
15
        [[[4.95, 52.40], [4.97, 52.40], [4.97, 52.42], [4.95, 52.42], [4.95, 52.40]]]
16
    ]
17
};

You can obtain a city boundary polygon directly from the SDK using geocodeOne and geometryData:

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

3
const geocodeResult = await geocodeOne('Amsterdam, Netherlands');
4
const boundaries = await geometryData({ geometries: [geocodeResult] });
5
const boundary = boundaries.features[0];
6

7
// Use the boundary geometry directly as the analysis region
8
const result = await trafficAreaAnalytics({
9
    startDate: '2024-08-06',
10
    dataTypes: ['SPEED', 'CONGESTION_LEVEL'],
11
    functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD', 'LOCAL_CONNECTING_ROAD', 'LOCAL_ROAD_HIGH_IMPORTANCE'],
12
    hours: [7, 8, 9, 17, 18],
13
    geometry: boundary.geometry,
14
});

Response Structure

The result is a TrafficAreaAnalytics FeatureCollection. Each feature corresponds to the submitted region.

Top-Level Properties

1
const { startDate, endDate, dataTypes, frcs } = result.properties; // frcs contains the numeric indices sent to the API

Feature Properties

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

Base Data

baseData contains the overall aggregated metrics for the full analysis period:

1
const {
2
    speed,           // average speed (km/h)
3
    freeFlowSpeed,   // free-flow speed (km/h)
4
    congestionLevel, // congestion % above free-flow
5
    travelTime,      // avg travel time per 10 km (minutes)
6
    networkLength,   // total road segment length with data (meters)
7
} = region.properties.baseData;

Only metrics included in dataTypes will be present.

Timed Data

timedData contains time-series breakdowns at multiple granularities. Each array entry includes the relevant time identifier and the same metric fields as baseData:

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

3
// Daily breakdown
4
timedData.daily?.forEach(entry => {
5
    console.log(entry.date, entry.speed, entry.congestionLevel);
6
});
7

8
// Hourly breakdown
9
timedData.hourly?.forEach(entry => {
10
    console.log(`Hour ${entry.hour}: speed=${entry.speed} km/h`);
11
});

Available granularities depend on the date range and requested hours.

Tiled Data

tiledData contains per-tile heatmap metrics when available. Each tile entry includes a tileCentre coordinate ([longitude, latitude]) and the requested metrics:

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

Anomalies

anomalies is a map from data type to detected traffic anomalies for that metric:

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

Multi-Day Analysis

1
// Continuous 7-day range using string dates
2
const result = await trafficAreaAnalytics({
3
    startDate: '2024-08-01',
4
    endDate: '2024-08-07',
5
    dataTypes: ['SPEED', 'FREE_FLOW_SPEED', 'CONGESTION_LEVEL', 'TRAVEL_TIME', 'NETWORK_LENGTH'],
6
    functionalRoadClasses: 'all',
7
    hours: 'all',
8
    geometry: {
9
        type: 'Polygon',
10
        coordinates: [[[4.89, 52.37], [4.91, 52.37], [4.91, 52.39], [4.89, 52.39], [4.89, 52.37]]]
11
    }
12
});
13

14
result.features[0].properties.timedData.daily?.forEach(day => {
15
    console.log(day.date?.toISOString().slice(0, 10), day.congestionLevel);
16
});

Error Handling

1
try {
2
    const result = await trafficAreaAnalytics({ /* ... */ });
3
} catch (error) {
4
    // SDKServiceError contains .status (HTTP code) and .service
5
    console.error('Traffic Area Analytics request failed:', error.message);
6
}

API Reference

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

Traffic Area Analytics NodeJS – Server-side analytics for a geocoded city

Traffic Incident Details – Real-time incident data for a geographic area
Geocode – Resolve place names to coordinates