Service version: 1
Last edit: 2022.08.22

Purpose

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

Request data

HTTPS Method: GET

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets &#123 } 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

https://{baseURL}/origindestination/{versionNumber}/analysis/flowmatrix/{id}?key={Your_API_Key}

Example

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

Request parameters

Required parameters

Description
baseURL
string

The base URL for calling TomTom services.


Value: api.tomtom.com
versionNumber
string

Version of the service to call.


Value: The current value is 1.

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
string
Information about the analysis.
analysisInfo.id
integer
Analysis number id.
analysisInfo.name
string
Job name, given for the user's convenience.
analysisInfo.owner
string
Email of the analysis' owner.
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.creationTime
datetime

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

analysisInfo.timeDefinition
time
Time definition of the analysis.
analysisInfo.tripsCounted
integer

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

analysisInfo.startAnalysisTime
datetime

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

analysisInfo.endAnalysisTime
datetime

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

analysisInfo.estimatedDuration
integer

Estimated time in seconds to change the analysis status from RUNNING to ENDED.

analysisInfo.type
string
Type of the created analysis.
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 available only when the analysis has a status of ACCEPTED.

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.

lengthsHistogramPartialResultLink
string

URL to the partial analysis trips lengths histogram result. Your API Key needs to be added to the URL.

hoursOfDayHistogramPartialResultLink
string

URL to the partial analysis trips start hour of day histogram result. Your API Key needs to be added to the URL.

tripsResultFileSize
integer

Trips result file size in megabytes. It will help you decide if you want to download the whole or a partial result.

dateRange
dateRange
Date range of the result.
dateRange.startDate
date

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

dateRange.endDate
dateRange

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

dateRange.exclusions
array

List of dates to exclude from the given range in YYYY-MM-DD format.

dateRange
time
Time range of the result.
timeRange.startTime
time

Start time of the time range in HH:mm format.

timeRange.endTime
time

End time of the time range in HH:mm format.

Trips response structure

Field

Description

links
array
Array of links between regions.

Response interpretation example

1{
2 "links": [[0,0,0,100], [0,1,1,200], ...]
3}

The response contains a list of 'links'. Each link contains information about trips between regions and looks like this:

[Origin region index (number), Destination region index (number), Via region index (number), Amount of trips (number)]

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

200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found