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

Analysis Creation

Request

Format

https://<baseURL>/origindestination/<versionNumber>/analysis/flowmatrix?key=<apiKey>

Example

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

Required POST Headers

Content-Type: application/json

Parameters

The table below describes the parameters that must be used in a request or the call will fail.

Request parameters
parameter Description Required? Type / Values Default Value

baseURL

Base URL for calling the API

Yes

api.tomtom.com

-

versionNumber

Service version number. The current value is 1.

Yes

1

-

apiKey

Authorization key for access to the API.

Yes

API Key

-

JSON request parameters

The table below describe all of the fields that can appear in a request.
Fields are listed by the response section.

Structure of 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.
(Limit: Maximum 200 regions with total area less than 3000 km^2)

Yes

List of regions

-

time

Time definition for calculations.

Yes

Time definition

-

passMatrix

When selected, trips will be trimmed to defined regions. 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.

No

Boolean

false

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

Regions definition example
{
...,
"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.38857707898845
            ]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Region 3"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              4.803606167831703,
              52.367271590070374
            ],
            [
              4.782206853183084,
              52.36291591838679
            ],
            [
              4.7903589730536,
              52.34720081992785
            ],
            [
              4.803606167831703,
              52.367271590070374
            ]
          ]
        ]
      }
    }
  ],
  ...
}

Time definition format

The table below describes the parameters that must be used in a request in time section.

Structure of time definition
Parameter Description Required? Type / Values Default Value

zoneId

Time zone that is used.

Yes

Time zone like: "Europe/Amsterdam" or "UTC"

-

daysOfWeek

Days of week to analyse.

Yes

List of values:

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

  • SUNDAY

-

dateRanges

List date ranges to analyse

(Limit: 4 date ranges)

Yes

List of Date ranges

-

timeRanges

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

Yes

List of Time ranges

-

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"
      }
    ]
  },
...
}

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

Date range structure
Field Description Required Type / Values

startDate

Start date of date range

Yes

Date in YYYY-MM-DD format

endDate

Start date of date range

Yes

Date in YYYY-MM-DD format

Time range format

Time range structure
Field Description Required Type / Values

startTime

Start time of time range

Yes

Time in HH:mm or HH:mm:ss format

endTime

End time of time range

Yes

Time in HH:mm or HH:mm:ss format

Response

The table below describe all of the fields that can appear in a response.

Structure of response (JSON)
Field(s) Description Type / Values

id

Analysis number id.

long

creationTime

Job creation time.

Timestamp in format: YYYY-MM-DDTHH:mm:ss.SSSZ

status

Job status.

String:

  • WAITING

  • RUNNING

  • ENDED

  • FAILED

  • CANCELLED

statusDetails

Optional details of status. E.g. what is the reason behind FAILED status.

String

type

Type of analysis.

String / "FLOW_MATRIX"

parameters

Parameters regarding analysis.
See structure time and regions.

Object with properties:

  • time

  • regions

  • name

  • timeWindow

  • separateHours

  • separateDaysOfWeek

  • pass Matrix

result

Flows & dimensions.

You can read more about details in Analysis Preview section

name

Job name, given for user’s convenience.

String

owner

Owner email who running this analysis.

String

startAnalysisTime

Date and time start of analysis.

Timestamp in format: YYYY-MM-DDTHH:mm:ss.SSSZ

endAnalysisTime

Date and time end of analysis.

Timestamp in format: YYYY-MM-DDTHH:mm:ss.SSSZ

currentProgress

Current value of job progress.

Integer (0-1000)

maxProgress

Maximum value of job progress.

Integer (1000)

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