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 Flow Matrix 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/flowmatrix?key={Your_API_Key}

Example

post

URL request example

1
https://api.tomtom.com/origindestination/1/analysis/flowmatrix?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 fields

Required fields	Description
`name` string	Job name string which will be used in the process and output. Given for the user’s convenience. (Limit: 1 to 254 characters.)
`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.
`regions` array	List of region definitions. The maximum number of regions and their maximum total area are part of the limits granted to your contract. Regions that declare a narrowed `regionRoles` set - one or two of `ORIGIN`, `DESTINATION` and `VIA`, see Regions definition format - count towards a higher ceiling, so an analysis built only from such regions may contain up to three times more of them. The convex hull of all regions may not exceed three times your granted total area.
`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.dateRanges` array (of objects)	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 objects)	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. A trip is counted in a time range if it entered its origin region within that range.

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)
`time.daysOfWeek` array (of strings)	Days of the week to analyze. Applies to every date range that does not declare its own `daysOfWeek`. Default value: all seven days. Possible values: `MONDAY` `TUESDAY` `WEDNESDAY` `THURSDAY` `FRIDAY` `SATURDAY` `SUNDAY`
`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, to avoid confusion. This parameter is used only if the convex hull area of the regions is below 3000 km^2, as map-matching is disabled for larger areas. Learn more in the user guide.
`excludeMotorwayStartEnd` boolean	Setting this parameter to `true` discards trips whose beginning or end matches a motorway or a slip road, or whose form of way could not be determined, because such a trip usually did not really start or end there. Default value: `false` The analysis computes all results from the remaining trips; normalized values are shares of the remaining total. The filter is applied only when the analysis is map-matched, which requires the same convex hull area below 3000 km^2 as `mapVersion`. The `isMapMatched` field of the preview response tells you whether it was. The filter also widens the area of map data the analysis loads, so the analysis may take longer to complete. This parameter is not returned in the preview response, so a finished analysis cannot be inspected to tell whether the filter was applied to it.
`tripStats` boolean	Setting this parameter as `true` adds histograms for the trips’ hours of the day, lengths, durations, and average speeds to the analysis result. Default value: `false` The option is turned off automatically when the analysis defines more than 600 regions.

Request POST body example

POST body example - JSON

post

POST request body - JSON

1
{
2
  "name": "test analysis",
3
  "analysisVersion": 2,
4
  "regions": [
5
    {
6
      "type": "Feature",
7
      "properties": {
8
        "name": "Region 1"
9
      },
10
      "geometry": {
11
        "type": "Polygon",
12
        "coordinates": [
13
          [
14
            [19.45307, 51.80322],
15
            [19.44902, 51.80309],
16
            [19.44501, 51.80272],
17
            [19.44108, 51.80211],
18
            [19.43726, 51.80127],
19
            [19.43359, 51.8002],
20
            [19.43012, 51.79891],
21
            [19.42686, 51.79741],
22
            [19.42386, 51.79573],
23
            [19.42114, 51.79387],
24
            [19.41872, 51.79185],
25
            [19.41664, 51.7897],
26
            [19.41491, 51.78744],
27
            [19.41355, 51.78507],
28
            [19.41256, 51.78264],
29
            [19.41197, 51.78016],
30
            [19.41177, 51.77766],
31
            [19.41198, 51.77515],
32
            [19.41257, 51.77267],
33
            [19.41356, 51.77024],
34
            [19.41493, 51.76788],
35
            [19.41666, 51.76561],
36
            [19.41875, 51.76346],
37
            [19.42116, 51.76145],
38
            [19.42388, 51.75959],
39
            [19.42688, 51.75791],
40
            [19.43014, 51.75642],
41
            [19.43361, 51.75513],
42
            [19.43728, 51.75406],
43
            [19.44109, 51.75321],
44
            [19.44502, 51.7526],
45
            [19.44903, 51.75224],
46
            [19.45307, 51.75211],
47
            [19.45712, 51.75224],
48
            [19.46112, 51.7526],
49
            [19.46505, 51.75321],
50
            [19.46887, 51.75406],
51
            [19.47253, 51.75513],
52
            [19.476, 51.75642],
53
            [19.47926, 51.75791],
54
            [19.48226, 51.75959],
55
            [19.48498, 51.76145],
56
            [19.4874, 51.76346],
57
            [19.48948, 51.76561],
58
            [19.49122, 51.76788],
59
            [19.49258, 51.77024],
60
            [19.49357, 51.77267],
61
            [19.49417, 51.77515],
62
            [19.49437, 51.77766],
63
            [19.49417, 51.78016],
64
            [19.49358, 51.78264],
65
            [19.4926, 51.78507],
66
            [19.49123, 51.78744],
67
            [19.4895, 51.7897],
68
            [19.48742, 51.79185],
69
            [19.48501, 51.79387],
70
            [19.48229, 51.79573],
71
            [19.47928, 51.79741],
72
            [19.47603, 51.79891],
73
            [19.47255, 51.8002],
74
            [19.46888, 51.80127],
75
            [19.46507, 51.80211],
76
            [19.46113, 51.80272],
77
            [19.45712, 51.80309],
78
            [19.45307, 51.80322]
79
          ]
80
        ]
81
      }
82
    },
83
    {
84
      "type": "Feature",
85
      "properties": {
86
        "name": "Region 2"
87
      },
88
      "geometry": {
89
        "type": "Polygon",
90
        "coordinates": [
91
          [
92
            [19.34042, 51.75914],
93
            [19.29603, 51.75914],
94
            [19.29503, 51.73687],
95
            [19.35623, 51.73541],
96
            [19.35623, 51.73562],
97
            [19.34042, 51.75914]
98
          ]
99
        ]
100
      }
101
    },
102
    {
103
      "type": "Feature",
104
      "properties": {
105
        "name": "Region 3"
106
      },
107
      "geometry": {
108
        "type": "Polygon",
109
        "coordinates": [
110
          [
111
            [19.44131, 51.73073],
112
            [19.44131, 51.71274],
113
            [19.47035, 51.71274],
114
            [19.47035, 51.73073],
115
            [19.44131, 51.73073]
116
          ]
117
        ]
118
      }
119
    },
120
    {
121
      "type": "Feature",
122
      "properties": {
123
        "name": "Region 4"
124
      },
125
      "geometry": {
126
        "type": "Polygon",
127
        "coordinates": [
128
          [
129
            [19.44131, 51.71274],
130
            [19.44131, 51.69476],
131
            [19.47035, 51.69476],
132
            [19.47035, 51.71274],
133
            [19.44131, 51.71274]
134
          ]
135
        ]
136
      }
137
    },
138
    {
139
      "type": "Feature",
140
      "properties": {
141
        "name": "Region 5"
142
      },
143
      "geometry": {
144
        "type": "Polygon",
145
        "coordinates": [
146
          [
147
            [19.47035, 51.73073],
148
            [19.47035, 51.71274],
149
            [19.49939, 51.71274],
150
            [19.49939, 51.73073],
151
            [19.47035, 51.73073]
152
          ]
153
        ]
154
      }
155
    },
156
    {
157
      "type": "Feature",
158
      "properties": {
159
        "name": "Region 6"
160
      },
161
      "geometry": {
162
        "type": "Polygon",
163
        "coordinates": [
164
          [
165
            [19.47035, 51.71274],
166
            [19.47035, 51.69476],
167
            [19.49939, 51.69476],
168
            [19.49939, 51.71274],
169
            [19.47035, 51.71274]
170
          ]
171
        ]
172
      }
173
    }
174
  ],
175
  "time": {
176
    "dateRanges": [
177
      {
178
        "startDate": "2026-04-25",
179
        "endDate": "2026-05-24",
180
        "exclusions": ["2026-04-29"]
181
      },
182
      {
183
        "startDate": "2026-04-29",
184
        "endDate": "2026-05-28"
185
      },
186
      {
187
        "startDate": "2026-05-27",
188
        "endDate": "2026-05-28",
189
        "name": "weekend"
190
      }
191
    ],
192
    "daysOfWeek": [
193
      "MONDAY",
194
      "TUESDAY",
195
      "WEDNESDAY",
196
      "THURSDAY",
197
      "FRIDAY",
198
      "SATURDAY",
199
      "SUNDAY"
200
    ],
201
    "timeRanges": [
202
      {
203
        "startTime": "07:00",
204
        "endTime": "10:00"
205
      },
206
      {
207
        "startTime": "16:00",
208
        "endTime": "19:00"
209
      }
210
    ],
211
    "zoneId": "Europe/Warsaw"
212
  },
213
  "tripStats": false
214
}

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-04-25 - 2026-05-24 : 07:00 - 10:00
2026-04-25 - 2026-05-24 : 16:00 - 19:00
2026-04-29 - 2026-05-28 : 07:00 - 10:00
2026-04-29 - 2026-05-28 : 16:00 - 19:00
2026-05-27 - 2026-05-28 : 07:00 - 10:00
2026-05-27 - 2026-05-28 : 16:00 - 19:00

Every period is a separate result, addressed by its dateRange and timeRange index.

Required POST headers

Header	Value
Content-Type	`application/json`

Regions definition format

Region should be defined as GeoJSON Feature Object or GeoJSON FeatureCollection Object. Each feature can only contain the following types of geometries: Polygon, MultiPolygon or LineString. Note that in the case of the FeatureCollection object each feature of that collection will be used as a separate region.

Regions are identified in every result by their index in this list, counted from 0.

The following feature properties are read:

Optional properties	Description
`name` string	Region name, used in the CSV outputs. When it is missing or empty, the region is named `Region {index}`. A comma in the name is replaced with a hyphen so that it does not break the CSV files.
`regionRoles` array (of strings)	Restricts the roles the region may play in the result. Default value: all three roles. Possible values: `ORIGIN`, `DESTINATION`, `VIA` At least one region of the analysis must carry a role.
`bidirectional` boolean	For a `LineString` region: whether traffic in both directions of the road is counted. Ignored for other geometry types. Default value: `false`
`orbisSegmentId` string	For a `LineString` region: the identifier of the TomTom Orbis Maps segment the region should be pinned to, instead of letting the service route the line. Ignored for other geometry types and when map matching is not used.

Date range format

Required fields	Description
`startDate` date	Start date of the date range in `YYYY-MM-DD` format.
`endDate` date	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, returned as a string.
`name` string	Job name, given for the user’s convenience.
`type` string	Analysis type. Always `FLOW_MATRIX` 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).
`estimatedDuration` integer	Estimated time in seconds to change the analysis status from `RUNNING` to `ENDED`. `null` until the estimate has been computed.
`creationTime` datetime	Job creation time in `YYYY-MM-DDTHH:mmZ` format.
`startAnalysisTime` datetime	Date and time start of the analysis in the format: `YYYY-MM-DDTHH:mmZ`. `null` until the job starts.
`endAnalysisTime` datetime	Date and time end of the analysis in the format: `YYYY-MM-DDTHH:mmZ`. `null` until the job finishes.
`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.
`tripStats` boolean	Field which indicates if this option was enabled.
`isMapMatched` boolean	Whether the service actually map-matched the traces of this analysis.
`map` object	The map used for map-matching. Not returned when the analysis is not map-matched.
`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.

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 fields

Request POST body example

Required POST headers

Regions definition format

Date range format

Time range format

Response data

Response structure

Errors

Response codes

HTTPS Method: `POST`