Flow Matrix Analysis
The Flow Matrix API calculates a statistics of origin and destination between all defined regions. It also provides all via waypoints for all origin and destination pairs.
This API is asynchronous.
There are some important notes about using this API:
-
The latitude and longitude coordinates are in EPSG4326 / WGS84 format for both input and output. Other coordinate systems are not supported.
-
The maximum supported region area sum in total is 3000 km^2 Requests with bigger region area sum will be rejected.
-
The maximum number of regions is 200.
-
The maximum number of date ranges is 12.
-
The maximum number of time ranges is 4.
-
As the service is asynchronous it can take a while before results are available, depending on how busy the service is. Do not repost your request multiple times if you do not get feedback within seconds, we will ensure that the results are delivered.
Analysis Creation
Request
Format
https://<baseURL>/traffic/od/rest/analysis/flowmatrix?key=<apiKey>
Required POST Headers
Content-Type: application/json
Parameters
| parameter | Description | Required? | Type / Values | Default Value |
|---|---|---|---|---|
|
baseURL |
Base URL for calling the API |
Yes |
api.tomtom.com |
- |
|
apiKey |
Authorization key for access to the API. |
Yes |
API Key |
- |
JSON request parameters
Below JSON parameters refer to POST request.
| parameter | Description | Required? | Type / Values | Default Value |
|---|---|---|---|---|
|
name |
Job name which will be used in the process and output. Given for user’s convenience. |
Yes |
String |
- |
|
regions |
Definition of regions in Geojson format. See structure here |
Yes |
String |
- |
|
time |
Time sets for calculations. See structure here |
Yes |
String |
- |
Regions format
Region should be defined using The GeoJSON Specification (RFC 7946) standard. If you define property called name it will be used as region name.
Here is example, showing correct GeoJson region definition
{
...,
"regions": [
{
"type": "Feature",
"properties": {
"name": "Region 2"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
4.7962183091980535,
52.38857707898845
],
[
4.848952334606025,
52.38857707898845
],
[
4.848952334606025,
52.378314404028
],
[
4.7962183091980535,
52.378314404028
],
[
4.7962183091980535,
52.38857707898845
]
]
]
}
},
{
"type": "Feature",
"properties": {
"name": "Region 3"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
4.803606167831703,
52.367271590070374
],
[
4.782206853183084,
52.36291591838679
],
[
4.7903589730536,
52.34720081992785
],
[
4.8127773026899945,
52.347823306336494
],
[
4.828826788680374,
52.358093066670136
],
[
4.822712698769664,
52.36493824792734
],
[
4.803606167831703,
52.367271590070374
]
]
]
}
},
{
"type": "Feature",
"properties": {
"name": "Region 4"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
4.857709690343315,
52.36315952752082
],
[
4.857709690343315,
52.34517312024633
],
[
4.88716539648199,
52.34517312024633
],
[
4.88716539648199,
52.36315952752082
],
[
4.857709690343315,
52.36315952752082
]
]
]
}
},
{
"type": "Feature",
"properties": {
"name": "Region 5"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
4.857709690343315,
52.34517312024633
],
[
4.857709690343315,
52.32718671297184
],
[
4.88716539648199,
52.32718671297184
],
[
4.88716539648199,
52.34517312024633
],
[
4.857709690343315,
52.34517312024633
]
]
]
}
},
{
"type": "Feature",
"properties": {
"name": "Region 6"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
4.88716539648199,
52.36315952752082
],
[
4.88716539648199,
52.34517312024633
],
[
4.916621102620665,
52.34517312024633
],
[
4.916621102620665,
52.36315952752082
],
[
4.88716539648199,
52.36315952752082
]
]
]
}
},
{
"type": "Feature",
"properties": {
"name": "Region 7"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
4.88716539648199,
52.34517312024633
],
[
4.88716539648199,
52.32718671297184
],
[
4.916621102620665,
52.32718671297184
],
[
4.916621102620665,
52.34517312024633
],
[
4.88716539648199,
52.34517312024633
]
]
]
}
}
],
...
}Time format
TODO: Opis
TODO: tabelka opisująca każdy parametr
Here is example, showing correct time definition example
{
...,
"time": {
"zoneId": "Europe/Amsterdam",
"daysOfWeek": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY"
],
"dateRanges": [
{
"startDate": "2017-01-01",
"endDate": "2017-12-31"
},
{
"startDate": "2016-01-01",
"endDate": "2016-12-31"
}
],
"timeRanges": [
{
"startTime": "00:00",
"endTime": "00:00"
},
{
"startTime": "07:00",
"endTime": "10:00"
}
]
},
...
}