Analysis Creation

Service version: 1
Last edit: 2022.07.25

Purpose

Create a Flow Matrix Analysis by sending a POST request.

Request data

Format

POST
URL request example
https://api.tomtom.com/origindestination/1/analysis/flowmatrix?key={apiKey}

Example

POST
URL request example
https://api.tomtom.com/origindestination/1/analysis/flowmatrix?key=test-api-key

Required POST Headers

HeaderValue
Content-Typeapplication/json

Parameters

ParameterDescription
apiKeyAuthorization key for access to the API.

Request body structure

FieldRequired?Description
nameyesJob name string which will be used in the process and output. Given for the user’s convenience.
regionsyesList of region definitions. format. (Limit: Maximum 200 regions with total area less than 3000 km^2.)
passMatrixnoSetting this parameter as true makes that the origin of the trip will be defined as a region where the trip was first seen and the destination will be defined as a region where the trip was last seen. Otherwise such trips will be counted to an additional External region.
tripsStatsnoSetting this parameter as true adds histograms about the trips' start hours of day, lengths, and durations to the analysis' result.
timeyesTime definition for the analysis.
time.zoneIdyesTime zone for the analysis as TZ database name. For example "Europe/Amsterdam" or "UTC".
time.daysOfWeekyesDays of week to analyze. Allowed values:
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY
time.dateRangesyesList 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.timeRangesyesList of time ranges to analyze (Limit: 24 time ranges).
time.timeRangeConditionnoDetermines if the whole trip should be in selected time ranges, only its start time or trip should overlap with the defined time range with any part. Allowed values:
  • WHOLE
  • STARTS
  • ANY_PART

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 and MultiPolygon. Note that in the case of the FeatureCollection object each feature of that collection will be used as a separate region. You may define the feature property called name, and it will be used as a region name. Otherwise the region name will be generated automatically.

Request body example

POST
Request body - JSON
1{
2 "name": "test analysis",
3 "regions": [
4 {
5 "type": "Feature",
6 "properties": {
7 "name": "Region 1"
8 },
9 "geometry": {
10 "type": "Polygon",
11 "coordinates": [
12 [
13 [
14 19.45307185088558,
15 51.80321536393615
16 ],
17 [
18 19.449021727986082,
19 51.803092258240426
20 ],
21 [
22 19.445010675789355,
23 51.802724128734056
24 ],
25 [
26 19.441077386191672,
27 51.802114526645084
28 ],
29 [
30 19.43725979722228,
31 51.801269332419736
32 ],
33 [
34 19.43359472543494,
35 51.80019669871891
36 ],
37 [
38 19.430117509378423,
39 51.79890697140382
40 ],
41 [
42 19.426861667655277,
43 51.79741258929061
44 ],
45 [
46 19.42385857492407,
47 51.79572796366337
48 ],
49 [
50 19.421137159011245,
51 51.79386933873235
52 ],
53 [
54 19.418723622077586,
55 51.79185463441047
56 ],
57 [
58 19.416641188533646,
59 51.789703272952316
60 ],
61 [
62 19.41490988212168,
63 51.78743599115547
64 ],
65 [
66 19.413546334281687,
67 51.78507463996162
68 ],
69 [
70 19.412563625600402,
71 51.782641973414044
72 ],
73 [
74 19.411971161807454,
75 51.78016142902701
76 ],
77 [
78 19.41177458543684,
79 51.7776569017017
80 ],
81 [
82 19.411975723917923,
83 51.77515251337947
84 ],
85 [
86 19.412572574502207,
87 51.7726723806599
88 ],
89 [
90 19.41355932607394,
91 51.77024038262403
92 ],
93 [
94 19.414926417537615,
95 51.76787993109565
96 ],
97 [
98 19.416660632127055,
99 51.76561374554443
100 ],
101 [
102 19.418745226642596,
103 51.763463634784
104 ],
105 [
106 19.42116009429694,
107 51.76145028754837
108 ],
109 [
110 19.42388195954049,
111 51.75959307394009
112 ],
113 [
114 19.42688460294473,
115 51.75790985963573
116 ],
117 [
118 19.430139113950382,
119 51.756416834609205
120 ],
121 [
122 19.43361416903743,
123 51.75512835799247
124 ],
125 [
126 19.437276332648036,
127 51.75405682053805
128 ],
129 [
130 19.441090377993,
131 51.753212525978924
132 ],
133 [
134 19.445019624698105,
135 51.75260359240231
136 ],
137 [
138 19.44902629010031,
139 51.75223587456384
140 ],
141 [
142 19.45307185088558,
143 51.75211290787135
144 ],
145 [
146 19.457117411670843,
147 51.75223587456384
148 ],
149 [
150 19.46112407707305,
151 51.75260359240231
152 ],
153 [
154 19.46505332377815,
155 51.753212525978924
156 ],
157 [
158 19.468867369123117,
159 51.75405682053805
160 ],
161 [
162 19.472529532733724,
163 51.75512835799247
164 ],
165 [
166 19.476004587820768,
167 51.756416834609205
168 ],
169 [
170 19.479259098826425,
171 51.75790985963573
172 ],
173 [
174 19.482261742230662,
175 51.75959307394009
176 ],
177 [
178 19.484983607474216,
179 51.76145028754837
180 ],
181 [
182 19.487398475128558,
183 51.763463634784
184 ],
185 [
186 19.489483069644095,
187 51.76561374554443
188 ],
189 [
190 19.49121728423354,
191 51.76787993109565
192 ],
193 [
194 19.49258437569721,
195 51.77024038262403
196 ],
197 [
198 19.493571127268947,
199 51.7726723806599
200 ],
201 [
202 19.49416797785323,
203 51.77515251337947
204 ],
205 [
206 19.49436911633431,
207 51.7776569017017
208 ],
209 [
210 19.4941725399637,
211 51.78016142902701
212 ],
213 [
214 19.493580076170748,
215 51.782641973414044
216 ],
217 [
218 19.492597367489466,
219 51.78507463996162
220 ],
221 [
222 19.491233819649473,
223 51.78743599115547
224 ],
225 [
226 19.489502513237507,
227 51.789703272952316
228 ],
229 [
230 19.48742007969357,
231 51.79185463441047
232 ],
233 [
234 19.48500654275991,
235 51.79386933873235
236 ],
237 [
238 19.482285126847085,
239 51.79572796366337
240 ],
241 [
242 19.47928203411588,
243 51.79741258929061
244 ],
245 [
246 19.47602619239273,
247 51.79890697140382
248 ],
249 [
250 19.472548976336213,
251 51.80019669871891
252 ],
253 [
254 19.468883904548875,
255 51.801269332419736
256 ],
257 [
258 19.465066315579485,
259 51.802114526645084
260 ],
261 [
262 19.4611330259818,
263 51.802724128734056
264 ],
265 [
266 19.45712197378507,
267 51.803092258240426
268 ],
269 [
270 19.45307185088558,
271 51.80321536393615
272 ]
273 ]
274 ]
275 }
276 },
277 {
278 "type": "Feature",
279 "properties": {
280 "name": "Region 2"
281 },
282 "geometry": {
283 "type": "Polygon",
284 "coordinates": [
285 [
286 [
287 19.340421680650508,
288 51.759143470231464
289 ],
290 [
291 19.296034150900113,
292 51.759143470231464
293 ],
294 [
295 19.295025343411965,
296 51.73686699111843
297 ],
298 [
299 19.356226331411563,
300 51.73540926849816
301 ],
302 [
303 19.356226331411563,
304 51.73561751746462
305 ],
306 [
307 19.340421680650508,
308 51.759143470231464
309 ]
310 ]
311 ]
312 }
313 },
314 {
315 "type": "Feature",
316 "properties": {
317 "name": "Region 3"
318 },
319 "geometry": {
320 "type": "Polygon",
321 "coordinates": [
322 [
323 [
324 19.441307260101098,
325 51.730730193782335
326 ],
327 [
328 19.441307260101098,
329 51.71274378650784
330 ],
331 [
332 19.470348137169708,
333 51.71274378650784
334 ],
335 [
336 19.470348137169708,
337 51.730730193782335
338 ],
339 [
340 19.441307260101098,
341 51.730730193782335
342 ]
343 ]
344 ]
345 }
346 },
347 {
348 "type": "Feature",
349 "properties": {
350 "name": "Region 4"
351 },
352 "geometry": {
353 "type": "Polygon",
354 "coordinates": [
355 [
356 [
357 19.441307260101098,
358 51.71274378650784
359 ],
360 [
361 19.441307260101098,
362 51.69475737923335
363 ],
364 [
365 19.470348137169708,
366 51.69475737923335
367 ],
368 [
369 19.470348137169708,
370 51.71274378650784
371 ],
372 [
373 19.441307260101098,
374 51.71274378650784
375 ]
376 ]
377 ]
378 }
379 },
380 {
381 "type": "Feature",
382 "properties": {
383 "name": "Region 5"
384 },
385 "geometry": {
386 "type": "Polygon",
387 "coordinates": [
388 [
389 [
390 19.470348137169708,
391 51.730730193782335
392 ],
393 [
394 19.470348137169708,
395 51.71274378650784
396 ],
397 [
398 19.499389014238318,
399 51.71274378650784
400 ],
401 [
402 19.499389014238318,
403 51.730730193782335
404 ],
405 [
406 19.470348137169708,
407 51.730730193782335
408 ]
409 ]
410 ]
411 }
412 },
413 {
414 "type": "Feature",
415 "properties": {
416 "name": "Region 6"
417 },
418 "geometry": {
419 "type": "Polygon",
420 "coordinates": [
421 [
422 [
423 19.470348137169708,
424 51.71274378650784
425 ],
426 [
427 19.470348137169708,
428 51.69475737923335
429 ],
430 [
431 19.499389014238318,
432 51.69475737923335
433 ],
434 [
435 19.499389014238318,
436 51.71274378650784
437 ],
438 [
439 19.470348137169708,
440 51.71274378650784
441 ]
442 ]
443 ]
444 }
445 }
446 ],
447 "time": {
448 "dateRanges": [
449 {
450 "startDate": "2021-04-27",
451 "endDate": "2021-05-26",
452 "exclusions": ["2021-05-01"]
453 },
454 {
455 "startDate": "2021-05-01",
456 "endDate": "2021-05-30"
457 }
458 ],
459 "daysOfWeek": [
460 "MONDAY",
461 "TUESDAY",
462 "WEDNESDAY",
463 "THURSDAY",
464 "FRIDAY",
465 "SATURDAY",
466 "SUNDAY"
467 ],
468 "timeRanges": [
469 {
470 "startTime": "07:00",
471 "endTime": "10:00"
472 },
473 {
474 "startTime": "16:00",
475 "endTime": "19:00"
476 }
477 ],
478 "zoneId": "Europe/Warsaw",
479 "timeRangeCondition": "WHOLE"
480 },
481 "passMatrix": false,
482 "tripStats": false
483}

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:

  • 2019-10-27 - 2019-11-26 : 07:00 - 10:00
  • 2019-10-27 - 2019-11-26 : 16:00 - 19:00
  • 2019-09-01 - 2019-09-30 : 07:00 - 10:00
  • 2019-09-01 - 2019-09-30 : 16:00 - 19:00

Date range format

FieldRequiredDescription
startDateyesStart date of the date range in YYYY-MM-DD format.
endDateyesEnd date of the date range in YYYY-MM-DD format.
exclusionsnoList of dates to exclude from the given range in YYYY-MM-DD format.

Time range format

FieldDescription
startTimeStart time of the time range in HH:mm format.
endTimeEnd 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

FieldDescription
idAnalysis number id.
nameJob name, given for the user’s convenience.
ownerEmail or API Key of the analysis' owner.
apiKeyAPI Key of the analysis' owner.
statusJob status. One of the following values:
  • WAITING
  • RUNNING
  • ENDED
  • FAILED
  • CANCELLED
  • ACCEPTED
  • REJECTED
currentProgressCurrent value of the job progress (0-100).
creationTimeJob creation time in YYYY-MM-DDTHH:mm:ss.SSSZ format.
timeDefinitionTime definition of the analysis.
timeDefinition.zoneIdTime zone as a TZ database name. For example "Europe/Amsterdam" or "UTC".
timeDefinition.daysOfWeekDays of the week of the analysis. Allowed values:
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY
timeDefinition.dateRangesList of date ranges of the analysis.
timeDefinition.timeRangesList of time ranges of the analysis.
tripsCountedHow many trips were counted. Updates when the analysis is in progress.
startAnalysisTimeDate and time start of the analysis in the format: YYYY-MM-DDTHH:mm:ss.SSSZ.
endAnalysisTimeDate and time end of the analysis in the format: YYYY-MM-DDTHH:mm:ss.SSSZ.
tripStatsField which indicates if this option was enabled.
passMatrixField which indicates if this option was enabled.
regionsLinkLink to download regions.

Errors

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

HTTP Response Codes

CodeReason
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found