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)

timeDefinition

Time definition for the analysis.

timeDefinition.zoneId

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

timeDefinition.daysOfWeek

Days of week to analyse.
Allowed values:

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

  • SUNDAY

timeDefinition.dateRanges

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

timeDefinition.timeRanges

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

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 2"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              4.7962183091980535,
              52.38857707898845
            ],
            [
              4.848952334606025,
              52.378314404028
            ],
            [
              4.7962183091980535,
              52.38857707898845
            ]
          ]
        ]
      }
    }
  ],
"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"
      }
    ]
  },
...
}

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:

  • 2017-01-01 - 2017-12-31 : 00:00 - 00:00

  • 2017-01-01 - 2017-12-31 : 07:00 - 10:00

  • 2016-01-01 - 2016-12-31 : 00:00 - 00:00

  • 2016-01-01 - 2016-12-31 : 07:00 - 10: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 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

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

You are here