Analysis Histogram Result as a CSV file

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 full histogram result as a CSV file by sending a GET request. The analysis must have been created with tripStats enabled.

Request data

Format

get

URL request format

1
https://api.tomtom.com/origindestination/1/analysis/flowmatrix/{id}/result/histogram/csv?key={Your_API_Key}&dateRange={dateRange}&timeRange={timeRange}&type={type}

Example

get

URL request example

1
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
`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 the day at which trips entered their origin region `LENGTHS` - trips lengths in kilometers `DURATIONS` - trips durations in minutes `AVG_SPEEDS` - average speeds in kilometers per hour `AVG_SPEEDS` is available only for an analysis that produced an average speeds histogram.

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. Ignored unless `includeVia=true`.

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. Ignored unless includeVia=true.

Response data

This response returns a CSV file containing one histogram per origin and destination pair, or per origin, destination and via combination when includeVia=true. The file is served as an attachment named {type}_{id}_{dateRange}_{timeRange}-v2.csv, with the histogram type in lower case.

Response structure

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

The key columns are Origin,Destination, or Origin,Via,Destination when includeVia=true. Note the order: the via column sits between the two, not after them.
The remaining columns are the histogram buckets, labeled with the lower bound of each bucket and sorted in ascending order. Only the buckets that carry traffic somewhere in the file get a column.

Each cell is the normalized trip count for this date range and time range, written with a dot as the decimal separator. A bucket with no traffic in a given row is written as 0.0.

Without includeVia the rows are the origin-destination view and all their cells together add up to about 100. With includeVia they are a drill-down by via region and add up to more, because a trip that passed through three regions is counted in three rows. See Normalized probe counts.

LENGTHS and DURATIONS describe the part of a trip that lies inside the analyzed regions. HOURS_OF_DAY is the hour at which the trip entered its origin region. For AVG_SPEEDS, trips whose average speed could not be computed are left out of both the buckets and the total.

Every key column names one of your own regions. A trip that starts or ends outside your regions is counted under the boundary region it entered or left. To see which trip ends fell outside your regions, use externalEndsCode in the trips result.

Response example

1
Origin,Destination,0,5,10,15,20,25,30,35,40,..
2
Region A,Region A,1.12,0.57,0.27,0.11,0.0,0.0,0.03,0.05,0.0,..
3
Region A,Region B,2.55,2.99,1.42,0.94,0.58,0.42,0.42,0.24,0.18,..
4
Region B,Region A,2.34,2.53,1.15,0.77,0.57,0.46,0.36,0.21,0.23,..
5
Region B,Region B,4.58,12.21,12.37,8.98,6.15,4.86,3.58,2.82,2.63,..

Response types

Type	Bucket columns
`HOURS_OF_DAY`	Labels `0` to `23`, one per hour. Only the hours with traffic get a column.
`DURATIONS`	No upper limit, one column per 5 minutes. A column labeled `10` covers durations from 10 up to 15 minutes.
`LENGTHS`	No upper limit, one column per kilometer.
`AVG_SPEEDS`	No upper limit, one column per 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