Analysis Creation

Important Note Explore ready-to-use traffic reports and data visualizations immediately by signing up for a 30-day free trial on the MOVE Portal. Once registered, you’ll receive an API key to start using the Traffic Analytics APIs right away. Alternatively, you may contact our Sales team for a tailored solution.

Purpose

Create a Selected Link Analysis by sending a POST request.

Analysis version and service version are two different things. The 1 in the request URL is the version of the service and it does not change. The version of the analysis is the analysisVersion field in the request body. To create a version 2 analysis, send "analysisVersion": 2. If you omit the field, the service creates a version 1 analysis, which is documented at Analysis Creation (version 1).

Request data

HTTPS Method: `POST`

For ease of viewing and identification:

Parameters enclosed in curly brackets { } must be replaced with their values.
Please 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

1
https://api.tomtom.com/origindestination/1/analysis/selected-link?key={Your_API_Key}

Example

post

URL request example

1
https://api.tomtom.com/origindestination/1/analysis/selected-link?key={Your_API_Key}

Request parameters

Required parameters	Description
`key` string	Authorization key for access to the API. Value: Your valid API Key.

Required parameters

Description

key
string

Authorization key for access to the API.

Value: Your valid API Key.

Request POST body structure

Required fields	Description
`name` string	Job name string which will be used in the process and output. Given for the user’s convenience.
`analysisVersion` integer	Version of the analysis to create. Value: `2` is required to create a version 2 analysis. The field itself is optional in the API and defaults to `1`, so a request that omits it creates a version 1 analysis instead.
`link` object	GeoJSON LineString (Limit: Maximum length of a link is 2 km.) GeoJSON Polygon (Limit: Maximum area is 3 km^2, unless a higher limit is granted to your contract.)
`time` object	Time definition for the analysis.
`time.zoneId` string	Time zone for the analysis as a TZ database name. For example `Europe/Amsterdam` or `UTC`.
`time.daysOfWeek` array (of strings)	Days of the week to analyze. Applies to every date range that does not declare its own `daysOfWeek`. Allowed values: `MONDAY` `TUESDAY` `WEDNESDAY` `THURSDAY` `FRIDAY` `SATURDAY` `SUNDAY`
`time.dateRanges` array (of dates)	List of date ranges to analyze. The earliest and the latest date you may request, and the maximum number of date ranges in a single analysis, are part of the limits granted to your contract. (Limit: a single date range cannot cover more days than the calendar year it starts in, that is 365 or 366 days.)
`time.timeRanges` array (of times)	List of time ranges to analyze. The maximum number of time ranges in a single analysis is part of the limits granted to your contract.

Optional fields	Description
`dataSources` string	Determines from what devices data will be used. Default value: `ALL` Possible values: `ALL_PASSENGER` - Passenger Vehicles `ALL_FLEET` - Fleet Management Vehicles `ALL` - All Vehicles (Passenger and Fleet combined)
`mapVersion` string	Optional parameter indicating which map version should be used for map-matching. If not provided, a map version will be selected automatically based on the selected date ranges. You can check the list of available maps at Available maps. The value of this parameter should align with the selected date range in order to avoid confusion. For an analysis that requests traffic volume, the map version has to be one that carries traffic volume data, and that is what the automatic selection picks. See Enhanced metrics. If your date ranges span two calendar years, the analysis accepts the traffic volume map version of either the first or the last day of the analysis period.
`bufferRadiusInMeters` integer	Radius of the analyzed area. Default value: `10,000` (10 km) For LineString: Accepts values from 5,000 (5 km) to 50,000 (50 km). For Polygon: Accepts values from 5,000 (5 km) to 10,000 (10 km).
`regionEntrancesFrcs` array (of integers)	List of functional road classes (FRCs) used to define entrance and exit roads for the specified region. This parameter restricts the analysis to selected road classes intersecting the region. Accepts values: 0 to 7. Note: Applied only if the provided geometry is a Polygon. Ignored for other geometry types (e.g., LineString).
`enhancedMetrics` array (of strings)	List of additional metrics to calculate for every node of the result tree. Default value: none. When the field is omitted, no additional metrics are calculated and the field is not returned in the response. Possible values: `TRAVEL_TIME_AND_DISTANCE` - adds the average travel time and the traveled distance to every node of the result. `VOLUME` - adds the estimated absolute traffic volume to every node of the result. Requires traffic volume data to be available for the requested `link` and date ranges, and has additional prerequisites. See Enhanced metrics for the full list of prerequisites.

Enhanced metrics

TRAVEL_TIME_AND_DISTANCE has no prerequisites beyond "analysisVersion": 2.

VOLUME enriches every node of the result with the estimated absolute traffic volume on it, a model estimate rather than a vehicle count. See the volume field under Node fields for how that estimate is derived and distributed across the result tree.

All of the following must hold:

The traffic volume data must cover the whole link geometry.
All requested date ranges must fall inside the period for which traffic volume data is available in that area, and the last requested day must be at least four days in the past. The response lists the period you may use.
The map version used for the analysis must be one that carries traffic volume data for the year of your date ranges. See the mapVersion row of the request POST body structure table for how that version is chosen, and Finding the map version that supports traffic volumes for how to look it up.
A LineString link must map-match to exactly one road segment, so it must not route over more than one.

Finding the map version that supports traffic volumes

Only one map version carries traffic volume data for a given calendar year, and it is not always the newest map available for the area. Ask the Available maps endpoint for it with onlyVolumeVersions=true and a from date taken from your analysis period, then pass the returned version as mapVersion in the analysis request.

Required POST headers

Header	Value
Content-Type	`application/json`

Request POST body example

post

Request body - JSON

1
{
2
  "name": "Selected Link Example",
3
  "analysisVersion": 2,
4
  "time": {
5
    "dateRanges": [
6
      {
7
        "startDate": "2026-01-05",
8
        "endDate": "2026-01-10"
9
      },
10
      {
11
        "startDate": "2026-02-05",
12
        "endDate": "2026-02-10"
13
      },
14
      {
15
        "startDate": "2026-02-09",
16
        "endDate": "2026-02-10",
17
        "name": "weekend"
18
      }
19
    ],
20
    "daysOfWeek": [
21
      "MONDAY",
22
      "TUESDAY",
23
      "WEDNESDAY",
24
      "THURSDAY",
25
      "FRIDAY",
26
      "SATURDAY",
27
      "SUNDAY"
28
    ],
29
    "timeRanges": [
30
      {
31
        "startTime": "08:00",
32
        "endTime": "12:00"
33
      },
34
      {
35
        "startTime": "15:00",
36
        "endTime": "19:00"
37
      }
38
    ],
39
    "zoneId": "Europe/Warsaw"
40
  },
41
  "link": {
42
    "type": "LineString",
43
    "coordinates": [
44
      [21.02143, 52.24896],
45
      [21.02401, 52.25008]
46
    ]
47
  }
48
}

All date ranges and all time ranges are multiplied to cover all possible time definitions. The preceding example has 3 date ranges and 2 time ranges, so it results in 6 different periods:

2026-01-05 - 2026-01-10 : 08:00 - 12:00
2026-01-05 - 2026-01-10 : 15:00 - 19:00
2026-02-05 - 2026-02-10 : 08:00 - 12:00
2026-02-05 - 2026-02-10 : 15:00 - 19:00
2026-02-09 - 2026-02-10 : 08:00 - 12:00
2026-02-09 - 2026-02-10 : 15:00 - 19:00

Request POST body example with traffic volumes

Replace {volumes_map_version} with the traffic volume map version for your analysis period, looked up as described in Finding the map version that supports traffic volumes.

post

Request body with volumes - JSON

1
{
2
  "name": "Selected Link Example with volumes",
3
  "analysisVersion": 2,
4
  "enhancedMetrics": ["VOLUME", "TRAVEL_TIME_AND_DISTANCE"],
5
  "mapVersion": "{volumes_map_version}",
6
  "time": {
7
    "dateRanges": [
8
      {
9
        "startDate": "2026-03-02",
10
        "endDate": "2026-03-08"
11
      }
12
    ],
13
    "daysOfWeek": [
14
      "MONDAY",
15
      "TUESDAY",
16
      "WEDNESDAY",
17
      "THURSDAY",
18
      "FRIDAY"
19
    ],
20
    "timeRanges": [
21
      {
22
        "startTime": "08:00",
23
        "endTime": "12:00"
24
      }
25
    ],
26
    "zoneId": "Europe/Warsaw"
27
  },
28
  "link": {
29
    "type": "LineString",
30
    "coordinates": [
31
      [21.02143, 52.24896],
32
      [21.02401, 52.25008]
33
    ]
34
  }
35
}

Date range format

Required fields	Description
`startDate` string	Start date of the date range in `YYYY-MM-DD` format.
`endDate` string	End date of the date range in `YYYY-MM-DD` format.

Optional fields	Description
`exclusions` array (of dates)	List of dates to exclude from the given range in `YYYY-MM-DD` format.
`daysOfWeek` array (of strings)	Days of the week for this date range only. When present, it overrides `time.daysOfWeek` for this range. The list must not be empty. Default value: the days of the week given as `time.daysOfWeek`.
`name` string	Date range name. Given for the user’s convenience. Value: A date range name. For example: `Last working week of January`. (Limit: 1 to 100 characters.) Default value: none. When the field is omitted, the date range has no name and the field is absent from the response.

Optional fields

Description

exclusions
array (of dates)

List of dates to exclude from the given range in YYYY-MM-DD format.

daysOfWeek
array (of strings)

Days of the week for this date range only. When present, it overrides time.daysOfWeek for this range. The list must not be empty.

Default value: the days of the week given as time.daysOfWeek.

name
string

Date range name. Given for the user’s convenience. Value: A date range name. For example: Last working week of January. (Limit: 1 to 100 characters.)

Default value: none. When the field is omitted, the date range has no name and the field is absent from the response.

Time range format

Required fields	Description
`startTime` string	Start time of the time range in `HH:mm` format.
`endTime` string	End time of the time range in `HH:mm` format.

NOTE: To analyze a whole day you should use 00:00 for both the startTime and endTime.

NOTE: A time range must be at least 1 hour long.

Response data

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

Response structure

Field	Description
`id` string	Analysis number id.
`name` string	Job name, given for the user’s convenience.
`type` string	Analysis type. Always `SELECTED_LINK` for this endpoint.
`analysisVersion` integer	Version of the created analysis. Use it to confirm that the analysis was created as version `2` and to decide which version of this documentation applies to its results.
`status` string	Job status. One of the following values: `WAITING` `RUNNING` `ENDED` `FAILED` `CANCELLED` `ACCEPTED` `REJECTED`
`currentProgress` integer	Current value of the job progress (0-100).
`creationTime` datetime	Job creation time in `YYYY-MM-DDTHH:mmZ` format.
`startAnalysisTime` datetime	Date and time start of the analysis in format: `YYYY-MM-DDTHH:mmZ`.
`endAnalysisTime` datetime	Date and time end of the analysis in format: `YYYY-MM-DDTHH:mmZ`.
`timeDefinition` object	Time definition of the analysis.
`timeDefinition.zoneId` string	Time zone as a TZ database name. For example `Europe/Amsterdam` or `UTC`.
`timeDefinition.daysOfWeek` array (of strings)	Days of the week of the analysis. Allowed values: `MONDAY` `TUESDAY` `WEDNESDAY` `THURSDAY` `FRIDAY` `SATURDAY` `SUNDAY`
`timeDefinition.dateRanges` array	List of date ranges of the analysis.
`timeDefinition.timeRanges` array	List of time ranges of the analysis.
`dataSources` string	Data sources the analysis runs on.
`enhancedMetrics` array (of strings)	Enhanced metrics the analysis was created with. Not returned when the request did not contain the field.
`link` object	The analyzed geometry, as a GeoJSON LineString or Polygon. For a LineString this is the geometry after map-matching, not the geometry you sent.
`edgeIds` array (of strings)	Identifiers of the map segments the link was matched to. Empty for a Polygon link.
`map` object	The map used for map-matching.
`map.version` string	Map version, as a string in the `YYYY.MM.NNNN` format.
`map.type` string	Name of the map the version belongs to.
`bufferRadiusInMeters` integer	Radius of the analyzed area, in meters.
`regionEntrancesFrcs` array (of integers)	Functional road classes used to define entrance and exit roads of the region. Omitted when not applicable.

Errors

If there is an error in the supplied parameters or any other internal problem, an error response is generated in the requested format.

Response codes

Code	Meaning & possible causes
`201`	Created
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found

Analysis Creation

Purpose

Request data

HTTPS Method: POST

Format

Example

Request parameters

Request POST body structure

Enhanced metrics

Finding the map version that supports traffic volumes

Required POST headers

Request POST body example

Request POST body example with traffic volumes

Date range format

Time range format

Response data

Response structure

Errors

Response codes

HTTPS Method: `POST`