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 { } 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
https://{baseURL}/origindestination/{versionNumber}/analysis/flowmatrix/{id}?key={Your_API_Key}

Example

get
URL request 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

Response body - JSON
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

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found