Developer

Analysis Creation

Service version: 1
Last edit: 2025.02.25
Try 30 Days Free

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.

Request data

HTTPS Method: POST

For ease of viewing and identification:

  • Constants and 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
https:/{baseURL}/origindestination/{versionNumber}/analysis/selected-link?key={Your_API_Key}

Example

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

Request parameters

Required parameters

Description

baseURL
string

The base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber
string

Version of the service to call.


Value: The current value is 1.

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.

link
string

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)

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 analyse. Allowed values:

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

  • SUNDAY

time.dateRanges
array (of dates)

List of date ranges to analyze. Date ranges must start not earlier than two years in the past and not end in the future. (Limits: 4 date ranges, each date range having no more than 365/366 days.)

time.timeRanges
array (of times)

List of time ranges to analyse (Limit: 24 time ranges).

Optional fields

Description

map.version
string

Deprecated - This property is deprecated and will be removed in the future. We recommend using the mapVersion property instead.

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.

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.

mapType
string

Determines the map generation used.
Default value: GENESIS
Possible values:

  • GENESIS - A map trusted by users for years, built on proprietary and partner data. As we continue to innovate, we are excited to introduce the new ORBIS map type, which offers better coverage, more features, and improved freshness and quality. In the future, this option will be marked as deprecated and removed.

  • ORBIS - The next generation of maps offers higher quality and accuracy compared to the GENESIS map type. TomTom Orbis Maps combine open map data and TomTom proprietary data that is validated, fresh, and of the highest quality. It also integrates data sources from Overture Maps Foundation™, OpenStreetMap (OSM), partner data and sensor-derived observations (SDOs). Read more about Orbis maps. This is recommended map type and will be set as default in the future.

bufferRadiusInMeters
integer

Radius of the analyzed area. If not specified, the default value of 10,000 (10 km) is used.

  • 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 from 1 to 6.
Note:

  • Applied only if the provided geometry is a Polygon.
  • Ignored for other geometry types (e.g., LineString).

Required POST headers

Header

Value

Content-Type

application/json

Request POST body example

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

All date ranges and all time ranges are multiplied to cover all possible time definitions. For the preceding example this will result in 4 different periods:

  • 2024-01-01 - 2024-01-06 : 08:00 - 12:00
  • 2024-01-01 - 2024-01-06 : 15:00 - 19:00
  • 2024-02-01 - 2024-02-06 : 08:00 - 12:00
  • 2024-02-01 - 2024-02-06 : 15:00 - 19:00

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.

name
string

Date range name. Given for the user's convenience. Value: A date range name. For example: "Last working week of January".

Time range format

FieldDescription

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 analyse a whole day you should use 00:00 for both the startTime and endTime.

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
integer

Analysis number id.

name
string

Job name, given for the user’s convenience.

owner
string

Email or API Key of the analysis' owner.

key
string

API Key of the analysis' owner.

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:mm:ss.SSSZ format.

timeDefinition
string

Time definition of the analysis.

timeDefinition.zoneId
string

Time zone as a TZ database name. For example "Europe/Amsterdam" or "UTC".

timeDefinition.daysOfWeek
string

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.

tripsCounted
integer

How many trips were counted. Updates when the analysis is in progress.

startAnalysisTime
datetime

Date and time start of the analysis in format: YYYY-MM-DDTHH:mm:ss.SSSZ.

endAnalysisTime
datetime

Date and time end of the analysis in format: YYYY-MM-DDTHH:mm:ss.SSSZ.

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