Analysis Preview

Important Note
Explore ready-to-use traffic reports and data visualizations immediately by signing up for a 30-day free trial on the MOVE Portal. Once registered, you’ll receive an API key to start using the Traffic Analytics APIs right away. Alternatively, you may contact our Sales team for a tailored solution.

Purpose

Get a preview of the analysis by sending a GET request.

Request data

HTTPS Method: `GET`

For ease of viewing and identification:

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

get

URL request format

1
https://api.tomtom.com/origindestination/1/analysis/flowmatrix/{id}?key={Your_API_Key}

Example

get

URL request example

1
https://api.tomtom.com/origindestination/1/analysis/flowmatrix/512?key={Your_API_Key}

Request parameters

Required parameters	Description
`id` integer	Analysis number id. Value: The analysis number id.
`key` string	Authorization key for access to the API. Value: Your valid API Key.

Required parameters

Description

id
integer

Analysis number id.

Value: The analysis number id.

key
string

Authorization key for access to the API.

Value: Your valid API Key.

Response data

Response structure

Field	Description
`analysisInfo` object	Information about the analysis.
`analysisInfo.id` string	Analysis number id, returned as a string.
`analysisInfo.name` string	Job name, given for the user’s convenience.
`analysisInfo.type` string	Analysis type. Always `FLOW_MATRIX` for this endpoint.
`analysisInfo.analysisVersion` integer	Version of the analysis. It decides the shape of every result of this analysis, so read it before parsing them.
`analysisInfo.status` string	Job status. One of the following values: `WAITING` `RUNNING` `ENDED` `FAILED` `CANCELLED` `ACCEPTED` `REJECTED`
`analysisInfo.currentProgress` integer	Current value of the job progress (0-100).
`analysisInfo.estimatedDuration` integer	Estimated time in seconds to change the analysis status from `RUNNING` to `ENDED`. `null` until the estimate has been computed.
`analysisInfo.creationTime` datetime	Job creation time in `YYYY-MM-DDTHH:mmZ` format.
`analysisInfo.startAnalysisTime` datetime	Date and time start of the analysis in the format: `YYYY-MM-DDTHH:mmZ`. `null` until the job starts.
`analysisInfo.endAnalysisTime` datetime	Date and time end of the analysis in the format: `YYYY-MM-DDTHH:mmZ`. `null` until the job finishes.
`analysisInfo.timeDefinition` object	Time definition of the analysis.
`analysisInfo.timeDefinition.zoneId` string	Time zone as a TZ database name. For example `Europe/Amsterdam` or `UTC`.
`analysisInfo.timeDefinition.daysOfWeek` array (of strings)	Days of the week of the analysis.
`analysisInfo.timeDefinition.dateRanges` array	List of date ranges of the analysis.
`analysisInfo.timeDefinition.timeRanges` array	List of time ranges of the analysis. A trip is counted in a time range if it entered its origin region within that range.
`analysisInfo.dataSources` string	Data sources the analysis runs on.
`analysisInfo.tripStats` boolean	Whether histogram trip statistics were enabled for the analysis.
`analysisInfo.isMapMatched` boolean	Whether the service actually map-matched the traces of this analysis.
`analysisInfo.map` object	The map used for map-matching, with `type` and `version`. Not returned when the analysis is not map-matched.
`regionsLink` string	URL to the regions defined in the analysis. Your API Key needs to be added to the URL.
`results` array	List of the results, one entry per date range and time range combination. Available only when the analysis has a status of `ACCEPTED`; the field is omitted otherwise.

Response example

Replace {map_version} with the map version the analysis actually ran on; the value is returned by the service and changes with the analyzed period.

Response body - JSON

1
{
2
  "analysisInfo": {
3
    "id": "4521660963097771615",
4
    "name": "Example analysis",
5
    "type": "FLOW_MATRIX",
6
    "status": "ACCEPTED",
7
    "currentProgress": 100,
8
    "estimatedDuration": 360,
9
    "creationTime": "2026-04-22T11:49Z",
10
    "startAnalysisTime": "2026-04-22T11:49Z",
11
    "endAnalysisTime": "2026-04-22T11:55Z",
12
    "timeDefinition": {
13
      "dateRanges": [
14
        {
15
          "startDate": "2026-04-06",
16
          "endDate": "2026-04-12",
17
          "exclusions": [],
18
          "daysOfWeek": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"]
19
        }
20
      ],
21
      "timeRanges": [
22
        {
23
          "startTime": "00:00",
24
          "endTime": "00:00"
25
        }
26
      ],
27
      "zoneId": "Europe/Warsaw",
28
      "daysOfWeek": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"],
29
      "timeRangeCondition": "ENTERS_REGION"
30
    },
31
    "tripStats": true,
32
    "dataSources": "ALL",
33
    "map": {
34
      "type": "OPEN_DSEG",
35
      "version": "{map_version}"
36
    },
37
    "mapMatchOption": "AUTO",
38
    "isMapMatched": true,
39
    "mapType": "ORBIS",
40
    "analysisVersion": 2
41
  },
42
  "regionsLink": "https://api.tomtom.com/origindestination/rest/analysis/4521660963097771615/regions?version=...",
43
  "results": [
44
    {
45
      "dateRange": {
46
        "startDate": "2026-04-06",
47
        "endDate": "2026-04-12",
48
        "exclusions": [],
49
        "daysOfWeek": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"]
50
      },
51
      "timeRange": {
52
        "startTime": "00:00",
53
        "endTime": "00:00"
54
      },
55
      "tripsResultFileSize": 1.63e-4,
56
      "tripsWholeResultLink": "https://api.tomtom.com/origindestination/rest/analysis/flowmatrix/.../result/trips?dateRange=0&timeRange=0",
57
      "tripsPartialResultLink": "https://api.tomtom.com/origindestination/rest/analysis/flowmatrix/.../result/partial/trips?dateRange=0&timeRange=0",
58
      "hoursOfDayHistogramPartialResultLink": "https://api.tomtom.com/origindestination/rest/analysis/flowmatrix/.../result/partial/histogram?dateRange=0&timeRange=0&type=HOURS_OF_DAY",
59
      "lengthsHistogramPartialResultLink": "https://api.tomtom.com/origindestination/rest/analysis/flowmatrix/.../result/partial/histogram?dateRange=0&timeRange=0&type=LENGTHS",
60
      "durationsHistogramPartialResultLink": "https://api.tomtom.com/origindestination/rest/analysis/flowmatrix/.../result/partial/histogram?dateRange=0&timeRange=0&type=DURATIONS",
61
      "avgSpeedsHistogramPartialResultLink": "https://api.tomtom.com/origindestination/rest/analysis/flowmatrix/.../result/partial/histogram?dateRange=0&timeRange=0&type=AVG_SPEEDS"
62
    }
63
  ]
64
}

Response link structure

Field	Description
`tripsWholeResultLink` string	URL to the whole analysis trips result.
`tripsPartialResultLink` string	URL to the partial analysis trips result. Your API Key needs to be added to the URL.
`durationsHistogramPartialResultLink` string	URL to the partial analysis trips duration histogram result. Your API Key needs to be added to the URL. Only present when `tripStats` was enabled.
`lengthsHistogramPartialResultLink` string	URL to the partial analysis trips lengths histogram result. Your API Key needs to be added to the URL. Only present when `tripStats` was enabled.
`hoursOfDayHistogramPartialResultLink` string	URL to the partial analysis trips hour of day histogram result. Your API Key needs to be added to the URL. Only present when `tripStats` was enabled.
`avgSpeedsHistogramPartialResultLink` string	URL to the partial analysis trips average speeds histogram result. Your API Key needs to be added to the URL. Only present when `tripStats` was enabled and the average speeds histogram was produced.
`tripsResultFileSize` number	Trips result file size in megabytes, as a decimal number. It will help you decide if you want to download the whole or a partial result.
`dateRange` object	Date range of the result.
`dateRange.startDate` date	Start date of the date range in `YYYY-MM-DD` format.
`dateRange.endDate` date	End date of the date range in `YYYY-MM-DD` format.
`dateRange.exclusions` array	List of dates excluded from the given range in `YYYY-MM-DD` format.
`dateRange.daysOfWeek` array (of strings)	Days of the week of this date range. Only present when the date range declared its own list.
`dateRange.name` string	Date range name. Only present when the date range was given one.
`timeRange` object	Time range of the result.
`timeRange.startTime` string	Start time of the time range in `HH:mm` format.
`timeRange.endTime` string	End time of the time range in `HH:mm` format.

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
`200`	OK
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found