Analysis Preview

Request Access
Service version: 1
Last edit: 2022.08.22

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 parametersDescription
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

FieldDescription
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

FieldDescription
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

FieldDescription
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

CodeMeaning & possible causes
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found