Service version: 1
Last edit: 2022.08.22

Purpose

Create a Flow Matrix Analysis by sending a POST request.

Request data

HTTPS Method: POST

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets &#123 } 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

https://{baseURL}/origindestination/{versionNumber}/analysis/flowmatrix?key={Your_API_Key}

Example

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

POST body example - 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 [19.45307185088558, 51.80321536393615],
14 [19.449021727986082, 51.803092258240426],
15 [19.445010675789355, 51.802724128734056],
16 [19.441077386191672, 51.802114526645084],
17 [19.43725979722228, 51.801269332419736],
18 [19.43359472543494, 51.80019669871891],
19 [19.430117509378423, 51.79890697140382],
20 [19.426861667655277, 51.79741258929061],
21 [19.42385857492407, 51.79572796366337],
22 [19.421137159011245, 51.79386933873235],
23 [19.418723622077586, 51.79185463441047],
24 [19.416641188533646, 51.789703272952316],
25 [19.41490988212168, 51.78743599115547],
26 [19.413546334281687, 51.78507463996162],
27 [19.412563625600402, 51.782641973414044],
28 [19.411971161807454, 51.78016142902701],
29 [19.41177458543684, 51.7776569017017],
30 [19.411975723917923, 51.77515251337947],
31 [19.412572574502207, 51.7726723806599],
32 [19.41355932607394, 51.77024038262403],
33 [19.414926417537615, 51.76787993109565],
34 [19.416660632127055, 51.76561374554443],
35 [19.418745226642596, 51.763463634784],
36 [19.42116009429694, 51.76145028754837],
37 [19.42388195954049, 51.75959307394009],
38 [19.42688460294473, 51.75790985963573],
39 [19.430139113950382, 51.756416834609205],
40 [19.43361416903743, 51.75512835799247],
41 [19.437276332648036, 51.75405682053805],
42 [19.441090377993, 51.753212525978924],
43 [19.445019624698105, 51.75260359240231],
44 [19.44902629010031, 51.75223587456384],
45 [19.45307185088558, 51.75211290787135],
46 [19.457117411670843, 51.75223587456384],
47 [19.46112407707305, 51.75260359240231],
48 [19.46505332377815, 51.753212525978924],
49 [19.468867369123117, 51.75405682053805],
50 [19.472529532733724, 51.75512835799247],
51 [19.476004587820768, 51.756416834609205],
52 [19.479259098826425, 51.75790985963573],
53 [19.482261742230662, 51.75959307394009],
54 [19.484983607474216, 51.76145028754837],
55 [19.487398475128558, 51.763463634784],
56 [19.489483069644095, 51.76561374554443],
57 [19.49121728423354, 51.76787993109565],
58 [19.49258437569721, 51.77024038262403],
59 [19.493571127268947, 51.7726723806599],
60 [19.49416797785323, 51.77515251337947],
61 [19.49436911633431, 51.7776569017017],
62 [19.4941725399637, 51.78016142902701],
63 [19.493580076170748, 51.782641973414044],
64 [19.492597367489466, 51.78507463996162],
65 [19.491233819649473, 51.78743599115547],
66 [19.489502513237507, 51.789703272952316],
67 [19.48742007969357, 51.79185463441047],
68 [19.48500654275991, 51.79386933873235],
69 [19.482285126847085, 51.79572796366337],
70 [19.47928203411588, 51.79741258929061],
71 [19.47602619239273, 51.79890697140382],
72 [19.472548976336213, 51.80019669871891],
73 [19.468883904548875, 51.801269332419736],
74 [19.465066315579485, 51.802114526645084],
75 [19.4611330259818, 51.802724128734056],
76 [19.45712197378507, 51.803092258240426],
77 [19.45307185088558, 51.80321536393615]
78 ]
79 ]
80 }
81 },
82 {
83 "type": "Feature",
84 "properties": {
85 "name": "Region 2"
86 },
87 "geometry": {
88 "type": "Polygon",
89 "coordinates": [
90 [
91 [19.340421680650508, 51.759143470231464],
92 [19.296034150900113, 51.759143470231464],
93 [19.295025343411965, 51.73686699111843],
94 [19.356226331411563, 51.73540926849816],
95 [19.356226331411563, 51.73561751746462],
96 [19.340421680650508, 51.759143470231464]
97 ]
98 ]
99 }
100 },
101 {
102 "type": "Feature",
103 "properties": {
104 "name": "Region 3"
105 },
106 "geometry": {
107 "type": "Polygon",
108 "coordinates": [
109 [
110 [19.441307260101098, 51.730730193782335],
111 [19.441307260101098, 51.71274378650784],
112 [19.470348137169708, 51.71274378650784],
113 [19.470348137169708, 51.730730193782335],
114 [19.441307260101098, 51.730730193782335]
115 ]
116 ]
117 }
118 },
119 {
120 "type": "Feature",
121 "properties": {
122 "name": "Region 4"
123 },
124 "geometry": {
125 "type": "Polygon",
126 "coordinates": [
127 [
128 [19.441307260101098, 51.71274378650784],
129 [19.441307260101098, 51.69475737923335],
130 [19.470348137169708, 51.69475737923335],
131 [19.470348137169708, 51.71274378650784],
132 [19.441307260101098, 51.71274378650784]
133 ]
134 ]
135 }
136 },
137 {
138 "type": "Feature",
139 "properties": {
140 "name": "Region 5"
141 },
142 "geometry": {
143 "type": "Polygon",
144 "coordinates": [
145 [
146 [19.470348137169708, 51.730730193782335],
147 [19.470348137169708, 51.71274378650784],
148 [19.499389014238318, 51.71274378650784],
149 [19.499389014238318, 51.730730193782335],
150 [19.470348137169708, 51.730730193782335]
151 ]
152 ]
153 }
154 },
155 {
156 "type": "Feature",
157 "properties": {
158 "name": "Region 6"
159 },
160 "geometry": {
161 "type": "Polygon",
162 "coordinates": [
163 [
164 [19.470348137169708, 51.71274378650784],
165 [19.470348137169708, 51.69475737923335],
166 [19.499389014238318, 51.69475737923335],
167 [19.499389014238318, 51.71274378650784],
168 [19.470348137169708, 51.71274378650784]
169 ]
170 ]
171 }
172 }
173 ],
174 "time": {
175 "dateRanges": [
176 {
177 "startDate": "2021-04-27",
178 "endDate": "2021-05-26",
179 "exclusions": ["2021-05-01"]
180 },
181 {
182 "startDate": "2021-05-01",
183 "endDate": "2021-05-30"
184 }
185 ],
186 "daysOfWeek": [
187 "MONDAY",
188 "TUESDAY",
189 "WEDNESDAY",
190 "THURSDAY",
191 "FRIDAY",
192 "SATURDAY",
193 "SUNDAY"
194 ],
195 "timeRanges": [
196 {
197 "startTime": "07:00",
198 "endTime": "10:00"
199 },
200 {
201 "startTime": "16:00",
202 "endTime": "19:00"
203 }
204 ],
205 "zoneId": "Europe/Warsaw",
206 "timeRangeCondition": "WHOLE"
207 },
208 "passMatrix": false,
209 "tripStats": false
210}

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.

regions
array

List of region definitions. format.

(Limit: Maximum 200 regions with total area less than 3000 km^2 .)

time
object
Time definition for the analysis.
time.zoneId
string

Time zone for the analysis as

TZ database name

. For example "Europe/Amsterdam" or "UTC".

time.daysOfWeek
array

Days of week to analyze. Allowed values:

  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY
time.dateRanges
array

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

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

Optional fields

Description

passMatrix
boolean

Setting 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.

tripsStats
boolean

Setting this parameter as true adds histograms about the trips' start hours of day, lengths, and durations to the analysis' result.

time.timeRangeCondition
string

Determines 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

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 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.

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

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

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

Time range format

Fields

Description

startTime
time

Start time of the time range in HH:mm format.

endTime
time

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
integher

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

startAnalysisTime
datetime

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

endAnalysisTime
datetime

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

tripStats
boolean
Field which indicates if this option was enabled.
passMatrix
boolean
Field which indicates if this option was enabled.
regionsLink
string
Link 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.

Response codes

Code

Meaning & possible causes

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