Analysis Preview

Request Access

Service version: 1

Last edit: 2024.08.05

Purpose

Perform a GET request to return an analysis preview.

Request data

Format

get

URL request format

https://{baseURL}/origindestination/{versionNumber}/analysis/selected-link/{id}?key={Your_API_Key}

Example

get

URL request example

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

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.apiKey` string	Authorization key used during creation.
`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` datetimer	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	The type of the created analysis. For the Selected Link Analysis the value is equal to `SELECTED_LINK`.
`analysisInfo.link` string	GeoJSON LineString object storing geometry of a link.
`analysisInfo.map` stringr	Map information used during the map matching process.
`analysisInfo.map.version` float	Map version used.
`analysisInfo.map.type` storing	The type of version used. Supported types are: `DSEG_NOSPLIT` and `OPEN_DSEG_NOSPLIT`.

Response link structure

Field	Description
`incomingResultUrl` integer	Section containing multiple supported formats of data. Each URL covers an incoming part of trips connected with a selected link.
`incomingResultUrl.json` integer	Incoming result in JSON format. Your API Key needs to be added to the URL.
`incomingResultUrl.protobuf` integer	Incoming result in protobuf format. Your API Key needs to be added to the URL.
`incomingResultUrl.shapefile` integer	Incoming result in shapefile format. Your API Key needs to be added to the URL.
`incomingResultUrl.csv` integer	Incoming result in CSV format. Your API Key needs to be added to the URL.
`outgoingResultUrl` integer	Section containing multiple supported formats of data. Each URL covers an outgoing part of trips connected with the selected link.
`outgoingResultUrl.json` integer	Outgoing result in JSON format. Your API Key needs to be added to the URL.
`outgoingResultUrl.protobuf` integer	Outgoing result in protobuf format. Your API Key needs to be added to the URL.
`outgoingResultUrl.shapefile` integer	Outgoing result in shapefile format. Your API Key needs to be added to the URL.
`outgoingResultUrl.csv` integer	Outgoing result in CSV format. Your API Key needs to be added to the URL.
`dateRange` integer	Date range of the result.
`dateRange.startDate` integer	Start date of the date range in `YYYY-MM-DD` format.
`dateRange.endDate` integer	End date of the date range in `YYYY-MM-DD` format.
`dateRange.exclusions` integer	List of dates to exclude from the given range in `YYYY-MM-DD` format.
`timeRange` integer	Time range of the result.
`timeRange.startTime` integer	Start time of the time range in `HH:mm` format.
`timeRange.endTime` integer	End time of the time range in `HH:mm` format.

Incoming/Outgoing Link response structure

Field	Description
`nodes` array	An array of nodes connected with the selected link.

JSON response example

get
Response body - JSON
1{
2  "nodeFormat" : ["id", "parentId", "trips", "geometry"],
3  "nodes": [[0,null,2941,[[21.00866,52.23521],[21.00838,52.23515]]],[1,0,44,[[21.00838,52.23515],[21.00835,52.23522]]],...]
4}

The result contains a list of 'nodes'. Each node contains the following information: [Id of link, Parent Id of link, Amount of trips (number), Geometry of link as GeoJSON LineString array].

If parentId is null, then this is the selected link of the analysis. We also provide self describing information under nodeFormat key.

CSV response example

get
Response body - CSV
1Id;Parent id;Trips;WKT
20;;2941;LINESTRING (21.00866 52.23521, 21.00838 52.23515)
31;0;44;LINESTRING (21.00838 52.23515, 21.00835 52.23522)
42;0;2877;LINESTRING (21.00838 52.23515, 21.0082 52.23512)
5...

The result contains nodes stored as separate rows in CSV format separated by a ; symbol.

If Parent id is empty, this means the given row is the selected link of the analysis.

Protobuf response example

For more information about the format you can check Protocol Buffers.

The following schema for the protobuf format is required to deserialize the results:

Protobuf schema format
1syntax = "proto3";
2
3message Point {
4    double lon = 1;
5    double lat = 2;
6}
7
8message Node {
9    optional uint32 parent_id = 1;
10    uint32 id = 2;
11    uint32 trips = 3;
12    repeated Point geo = 4;
13}
14
15message Result {
16    repeated Node nodes = 1;
17}

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