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

ParameterDescription

id

Analysis number id.

apiKey

Authorization key for access to the API.

Response

Response structure

FieldDescription

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

FieldDescription

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

FieldDescription

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

CodeReason

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found