Sorry, you need to enable JavaScript to visit this website.

Analysis Creation

Request

Create an analysis by sending a POST request.

https://api.tomtom.com/origindestination/1/analysis/flowmatrix?key=<apiKey>

Example

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

Required POST Headers

Header Value

Content-Type

application/json

Parameters

Parameter Description

apiKey

Authorization key for access to the API.

Request body stucture

Field Description

name

Job name string which will be used in the process and output. Given for user’s convenience.

regions

List of region definitions. format. (Limit: Maximum 200 regions with total area less than 3000 km^2)

passMatrix

Setting this parameter as true makes that origin of the trip will be defined as a region where trip was first seen and destination will be defined as a region where trip was last seen. Otherwise such trips will be counted to additional External region.

tripsStats

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

time

Time definition for the analysis.

time.zoneId

Time zone for the analysis as TZ database name. For example "Europe/Amsterdam" or "UTC"

time.daysOfWeek

Days of week to analyse. Allowed values:

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

  • SUNDAY

time.dateRanges

List of date ranges to analyse. Date ranges must start at least two years ago and not end in the future. (Limit: 4 date ranges)

time.timeRanges

List of time ranges to analyse (Limit: 4 time ranges)

time.timeRangeCondition

Determines if whole trip should be in selected time ranges or only its start time. Allowed values:

  • WHOLE

  • STARTS

Regions definition format

Region should be defined as GeoJSON Feature Object or GeoJSON FeatureCollection Object. Each feature can contain only following types of geometries: Polygon and MultiPolygon. Note that in case of FeatureCollection object each feature of that collection will be used as a separate region. You may define feature property called name and it will be used as a region name otherwise region name will be generated automatically.

Request body example

{
  "name": "test analysis",
  "regions": [
    {
      "type": "Feature",
      "properties": {
        "name": "Region 1"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              19.45307185088558,
              51.80321536393615
            ],
            [
              19.449021727986082,
              51.803092258240426
            ],
            [
              19.445010675789355,
              51.802724128734056
            ],
            [
              19.441077386191672,
              51.802114526645084
            ],
            [
              19.43725979722228,
              51.801269332419736
            ],
            [
              19.43359472543494,
              51.80019669871891
            ],
            [
              19.430117509378423,
              51.79890697140382
            ],
            [
              19.426861667655277,
              51.79741258929061
            ],
            [
              19.42385857492407,
              51.79572796366337
            ],
            [
              19.421137159011245,
              51.79386933873235
            ],
            [
              19.418723622077586,
              51.79185463441047
            ],
            [
              19.416641188533646,
              51.789703272952316
            ],
            [
              19.41490988212168,
              51.78743599115547
            ],
            [
              19.413546334281687,
              51.78507463996162
            ],
            [
              19.412563625600402,
              51.782641973414044
            ],
            [
              19.411971161807454,
              51.78016142902701
            ],
            [
              19.41177458543684,
              51.7776569017017
            ],
            [
              19.411975723917923,
              51.77515251337947
            ],
            [
              19.412572574502207,
              51.7726723806599
            ],
            [
              19.41355932607394,
              51.77024038262403
            ],
            [
              19.414926417537615,
              51.76787993109565
            ],
            [
              19.416660632127055,
              51.76561374554443
            ],
            [
              19.418745226642596,
              51.763463634784
            ],
            [
              19.42116009429694,
              51.76145028754837
            ],
            [
              19.42388195954049,
              51.75959307394009
            ],
            [
              19.42688460294473,
              51.75790985963573
            ],
            [
              19.430139113950382,
              51.756416834609205
            ],
            [
              19.43361416903743,
              51.75512835799247
            ],
            [
              19.437276332648036,
              51.75405682053805
            ],
            [
              19.441090377993,
              51.753212525978924
            ],
            [
              19.445019624698105,
              51.75260359240231
            ],
            [
              19.44902629010031,
              51.75223587456384
            ],
            [
              19.45307185088558,
              51.75211290787135
            ],
            [
              19.457117411670843,
              51.75223587456384
            ],
            [
              19.46112407707305,
              51.75260359240231
            ],
            [
              19.46505332377815,
              51.753212525978924
            ],
            [
              19.468867369123117,
              51.75405682053805
            ],
            [
              19.472529532733724,
              51.75512835799247
            ],
            [
              19.476004587820768,
              51.756416834609205
            ],
            [
              19.479259098826425,
              51.75790985963573
            ],
            [
              19.482261742230662,
              51.75959307394009
            ],
            [
              19.484983607474216,
              51.76145028754837
            ],
            [
              19.487398475128558,
              51.763463634784
            ],
            [
              19.489483069644095,
              51.76561374554443
            ],
            [
              19.49121728423354,
              51.76787993109565
            ],
            [
              19.49258437569721,
              51.77024038262403
            ],
            [
              19.493571127268947,
              51.7726723806599
            ],
            [
              19.49416797785323,
              51.77515251337947
            ],
            [
              19.49436911633431,
              51.7776569017017
            ],
            [
              19.4941725399637,
              51.78016142902701
            ],
            [
              19.493580076170748,
              51.782641973414044
            ],
            [
              19.492597367489466,
              51.78507463996162
            ],
            [
              19.491233819649473,
              51.78743599115547
            ],
            [
              19.489502513237507,
              51.789703272952316
            ],
            [
              19.48742007969357,
              51.79185463441047
            ],
            [
              19.48500654275991,
              51.79386933873235
            ],
            [
              19.482285126847085,
              51.79572796366337
            ],
            [
              19.47928203411588,
              51.79741258929061
            ],
            [
              19.47602619239273,
              51.79890697140382
            ],
            [
              19.472548976336213,
              51.80019669871891
            ],
            [
              19.468883904548875,
              51.801269332419736
            ],
            [
              19.465066315579485,
              51.802114526645084
            ],
            [
              19.4611330259818,
              51.802724128734056
            ],
            [
              19.45712197378507,
              51.803092258240426
            ],
            [
              19.45307185088558,
              51.80321536393615
            ]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Region 2"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              19.340421680650508,
              51.759143470231464
            ],
            [
              19.296034150900113,
              51.759143470231464
            ],
            [
              19.295025343411965,
              51.73686699111843
            ],
            [
              19.356226331411563,
              51.73540926849816
            ],
            [
              19.356226331411563,
              51.73561751746462
            ],
            [
              19.340421680650508,
              51.759143470231464
            ]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Region 3"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              19.441307260101098,
              51.730730193782335
            ],
            [
              19.441307260101098,
              51.71274378650784
            ],
            [
              19.470348137169708,
              51.71274378650784
            ],
            [
              19.470348137169708,
              51.730730193782335
            ],
            [
              19.441307260101098,
              51.730730193782335
            ]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Region 4"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              19.441307260101098,
              51.71274378650784
            ],
            [
              19.441307260101098,
              51.69475737923335
            ],
            [
              19.470348137169708,
              51.69475737923335
            ],
            [
              19.470348137169708,
              51.71274378650784
            ],
            [
              19.441307260101098,
              51.71274378650784
            ]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Region 5"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              19.470348137169708,
              51.730730193782335
            ],
            [
              19.470348137169708,
              51.71274378650784
            ],
            [
              19.499389014238318,
              51.71274378650784
            ],
            [
              19.499389014238318,
              51.730730193782335
            ],
            [
              19.470348137169708,
              51.730730193782335
            ]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Region 6"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              19.470348137169708,
              51.71274378650784
            ],
            [
              19.470348137169708,
              51.69475737923335
            ],
            [
              19.499389014238318,
              51.69475737923335
            ],
            [
              19.499389014238318,
              51.71274378650784
            ],
            [
              19.470348137169708,
              51.71274378650784
            ]
          ]
        ]
      }
    }
  ],
  "time": {
    "dateRanges": [
      {
        "startDate": "2019-10-27",
        "endDate": "2019-11-26"
      },
      {
        "startDate": "2019-09-01",
        "endDate": "2019-09-30"
      }
    ],
    "daysOfWeek": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY",
      "SATURDAY",
      "SUNDAY"
    ],
    "timeRanges": [
      {
        "startTime": "07:00",
        "endTime": "10:00"
      },
      {
        "startTime": "16:00",
        "endTime": "19:00"
      }
    ],
    "zoneId": "Europe/Warsaw",
    "timeRangeCondition": "WHOLE"
  },
  "passMatrix": false,
  "tripStats": false
}

All date ranges and all time ranges are multiplied to cover all possible time definitions. For above 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

Field Description

startDate

Start date of date range in YYYY-MM-DD format

endDate

End date of date range in YYYY-MM-DD format

Time range format

Field Description

startTime

Start time of time range in HH:mm format

endTime

End time of time range in HH:mm format

If the start time is the same as the end time the whole day will be used for the analysis.

Response

This response will return information about the created analysis. The table below describe all of the fields that can appear in a response.

Reponse structure

Field Description

id

Analysis number id.

name

Job name, given for user’s convenience.

owner

Email or api key of the analysis' owner

apiKey

Api key of the analysis' owner

status

Job status. One of the following values:

  • WAITING

  • RUNNING

  • ENDED

  • FAILED

  • CANCELLED

currentProgress

Current value of job progress (0-100)

creationTime

Job creation time in YYYY-MM-DDTHH:mm:ss.SSSZ format

timeDefinition

Time definition of the analysis.

timeDefinition.zoneId

Time zone as TZ database name. For example "Europe/Amsterdam" or "UTC"

timeDefinition.daysOfWeek

Days of week of the analysis. Allowed values:

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

  • SUNDAY

timeDefinition.dateRanges

List of date ranges of the analysis

timeDefinition.timeRanges

List of time ranges of the analysis

tripsCounted

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

startAnalysisTime

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

endAnalysisTime

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

tripStats

Field which indicates if this option was enabled

passMatrix

Field which indicates if this option was enabled

regionsLink

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.

HTTP Response Codes
Code Reason

201

Created

401

Unauthorized

403

Forbidden

404

Not Found