Analysis Histogram Result as a CSV file

Request Access

Service version: 1

Last edit: 2022.08.22

Purpose

Get a full histogram result as a CSV file by sending a GET request.

Request data

Format

get

URL request format

https://{baseURL}/origindestination/{versionNumber}/analysis/flowmatrix/{id}/result/histogram/csv?key={Your_API_Key}&dateRange={dateRange}&timeRange={timeRange}&type={type}

Example

get

URL request example

https://api.tomtom.com/origindestination/1/analysis/flowmatrix/123/result/histogram/csv?key=test-api-key&dateRange=0&timeRange=0&type=HOURS_OF_DAY

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.
`dateRange` integer	Index of the date range. Value: Example: `0`
`timeRange` integer	Index of the time range. Value: Example: `0`
`type` string	Type of the histogram. Values: One of the following values: `HOURS_OF_DAY` - hour of day when trips started `LENGTHS` - trips lengths in kilometers `DURATIONS` - trips durations in minutes with 20 minutes interval `AVG_SPEEDS` - average speeds in kilometers per hour
`includeVia` boolean	Determines if via information should be included in the results. Useful when you want to download results passed by given regions. Value: Example: `true` Default: `false`
`origins` Array of regions indexes	Limits the result to containing given origins determined as list of region indexes. Useful to reduce the size of the downloaded CSV file. Value: Example: `1,2,3` Default: All regions included.
`destinations` Array of regions indexes	Limits the result to containing given destinations determined as list of region indexes. Useful to reduce the size of the downloaded CSV file. Value: Example: `1` Default: All regions included.
`vias` Array of regions indexes	Limits the result to containing given vias determined as list of region indexes. Useful to reduce the size of the downloaded CSV file. Value: Example: `1` Default: All regions included.

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.

dateRange
integer

Index of the date range.

Value: Example: 0

timeRange
integer

Index of the time range.

Value: Example: 0

type
string

Type of the histogram.

Values: One of the following values:

HOURS_OF_DAY - hour of day when trips started
LENGTHS - trips lengths in kilometers
DURATIONS - trips durations in minutes with 20 minutes interval
AVG_SPEEDS - average speeds in kilometers per hour

Optional parameters

Description

includeVia

boolean

Determines if via information should be included in the results. Useful when you want to download results passed by given regions.

Value: Example: true

Default: false

origins

Array of regions indexes

Limits the result to containing given origins determined as list of region indexes. Useful to reduce the size of the downloaded CSV file.

Value: Example: 1,2,3

Default: All regions included.

destinations

Array of regions indexes

Limits the result to containing given destinations determined as list of region indexes. Useful to reduce the size of the downloaded CSV file.

Value: Example: 1

Default: All regions included.

vias

Array of regions indexes

Limits the result to containing given vias determined as list of region indexes. Useful to reduce the size of the downloaded CSV file.

Value: Example: 1

Default: All regions included.

Response data

This response will return a CSV file containing all histograms for all possible combinations of single origin and destination. The array size depends on the histogram type you choose.

Response structure

The response contains a CSV which should be self describing. The first row contains labels and the following rows contain data.

The first two columns are reserved for region names.
The rest of them are reserved for histograms values.

Response example

1Origin,Destination,0,5,10,15,20,25,30,35,40,..
2Region A,Region A,41,21,10,4,0,0,1,2,0,..
3Region A,External,473,555,263,174,107,78,78,45,34,..
4External,Region A,435,469,213,142,105,86,66,39,42,..
5External,External,850,2265,2294,1666,1141,902,665,524,487,..

Response types

Type	Size of array
`HOURS_OF_DAY`	24
`DURATIONS`	No limitation (contains all durations buckets for minimal interval of 5 minutes).
`LENGTHS`	No limitation (contains all length buckets for minimal interval of 1 kilometer).
`AVG_SPEEDS`	No limitation (contains all average speed buckets for a minimal interval of 1 kilometer per hour).

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