Analysis Preview

Request

Format

GET

URL request example

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

Example

GET

URL request example

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

Parameters

Parameter	Description
id	Analysis number id.
apiKey	Authorization key for access to the API.

Response

Response structure

Field	Description
analysisInfo	Information about the analysis
analysisInfo.id	Analysis number id.
analysisInfo.name	Job name, given for user’s convenience.
analysisInfo.owner	Email of the analysis' owner
analysisInfo.apiKey	Authorization key used during creation.
analysisInfo.status	Job status. One of the following values: WAITING RUNNING ENDED FAILED CANCELLED ACCEPTED REJECTED
analysisInfo.currentProgress	Current value of job progress (0-100)
analysisInfo.creationTime	Job creation time in `YYYY-MM-DDTHH:mm:ss.SSSZ` format
analysisInfo.timeDefinition	Time definition of the analysis
analysisInfo.tripsCounted	How many trips were counted. Updates when analysis is in progress.
analysisInfo.startAnalysisTime	Date and time start of analysis in format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
analysisInfo.endAnalysisTime	Date and time end of analysis in format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
analysisInfo.estimatedDuration	Estimated time in seconds to change analysis status from RUNNING to ENDED
analysisInfo.type	Type of created analysis. For Selected Link Analysis value is equal to SELECTED_LINK
analysisInfo.link	GeoJSON LineString object storing geometry of link.
analysisInfo.map	Map information used during map matching process.
analysisInfo.map.version	Map version used.
analysisInfo.map.type	Type of version used. Supported types are: DSEG_NOSPLIT and OPEN_DSEG_NOSPLIT

Result link structure

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

Incoming/Outgoing Link result structure

Field	Description
nodes	Array of nodes connected with selected link

JSON result interpretation 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}

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

If parentId is null this means, this is selected link of analysis.

We also provide self describing information under nodeFormat key.

CSV result interpretation 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...

Result contains nodes stored as separate rows in csv format separated by ; symbol.

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

Protobuf result interpretation example

For more information about format you can check here

Schema for protobuf format required to deserialize results:

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

Errors

If there is an error in the supplied parameters or any other internal problem an error response is generated in the requested format.

HTTP Response Codes

Code	Reason
200	OK
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found