Analysis Creation
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 { } 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 |
---|---|
| The base URL for calling TomTom services. Value: |
| Version of the service to call. Value: The current value is |
| 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": "2024-04-27",178 "endDate": "2024-05-26",179 "exclusions": ["2024-05-01"]180 },181 {182 "startDate": "2024-05-01",183 "endDate": "2024-05-30"184 },185 {186 "startDate": "2024-05-29",187 "endDate": "2024-05-30",188 "name": "weekend"189 }190 ],191 "daysOfWeek": [192 "MONDAY",193 "TUESDAY",194 "WEDNESDAY",195 "THURSDAY",196 "FRIDAY",197 "SATURDAY",198 "SUNDAY"199 ],200 "timeRanges": [201 {202 "startTime": "07:00",203 "endTime": "10:00"204 },205 {206 "startTime": "16:00",207 "endTime": "19:00"208 }209 ],210 "zoneId": "Europe/Warsaw",211 "timeRangeCondition": "WHOLE"212 },213 "passMatrix": false,214 "tripStats": false215}
Request POST body fields
Required fields | Description |
---|---|
| Job name string which will be used in the process and output. Given for the user’s convenience. |
| List of region definitions. format. (Limit: Maximum 600 regions with total area less than 20000 km^2 .) |
| Determines from what devices data will be used.
|
| Time definition for the analysis. |
| Time zone for the analysis as TZ database name. For example "Europe/Amsterdam" or "UTC". |
| Days of week to analyze. Allowed values:
|
| 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.) |
| List of time ranges to analyze (Limit: 24 time ranges). |
Optional fields | Description |
---|---|
| Setting this parameter as |
| Setting this parameter as |
| 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:
|
Required POST headers
Header | Value |
---|---|
|
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. 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:
2024-10-27 - 2024-11-26 : 07:00 - 10:00
2024-10-27 - 2024-11-26 : 16:00 - 19:00
2024-09-01 - 2024-09-30 : 07:00 - 10:00
2024-09-01 - 2024-09-30 : 16:00 - 19:00
Date range format
Required fields | Description |
---|---|
| Start date of the date range in |
| End date of the date range in |
Optional fields | Description |
---|---|
| List of dates to exclude from the given range in |
| Date range name. Given for the user's convenience. Value: A date range name. For example: "Last working week of January". |
Time range format
Fields | Description |
---|---|
| Start time of the time range in |
| End time of the time range in |
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 |
---|---|
| Analysis number id. |
| Job name, given for the user’s convenience. |
| Email or API Key of the analysis' owner. |
| API Key of the analysis' owner. |
| Job status. One of the following values:
|
| Current value of the job progress (0-100). |
| Job creation time in |
| Time definition of the analysis. |
| Time zone as a TZ database name. For example "Europe/Amsterdam" or "UTC". |
| Days of the week of the analysis. Allowed values:
|
| List of date ranges of the analysis. |
| List of time ranges of the analysis. |
| How many trips were counted. Updates when the analysis is in progress. |
| Date and time start of the analysis in the format:
|
| Date and time end of the analysis in the format:
|
| Field which indicates if this option was enabled. |
| Field which indicates if this option was enabled. |
| 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 |
---|---|
| Created |
| Bad Request |
| Unauthorized |
| Forbidden |
| Not Found |