Analysis Creation

Request

Create Selected Link Analysis by sending a POST request.

Format

POST
URL request example
https://api.tomtom.com/origindestination/1/analysis/selected-link?key={apiKey}

Example

POST
URL request example
https://api.tomtom.com/origindestination/1/analysis/selected-link?key=test-api-key

Required POST Headers

HeaderValue

Content-Type

application/json

Parameters

ParameterDescription

apiKey

Authorization key for access to the API.

Request body structure

FieldRequiredDescription

name

yes

Job name string which will be used in the process and output. Given for user’s convenience.

link

yes

GeoJSON LineString is the correct definition of a link. (Limit: Maximum length of a link is 10 km)

time

yes

Time definition for the analysis.

time.zoneId

yes

Time zone for the analysis as TZ database name. For example "Europe/Amsterdam" or "UTC"

time.daysOfWeek

yes

Days of week to analyse. Allowed values:

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

  • SUNDAY

time.dateRanges

yes

List of date ranges to analyse. Date ranges must start not earlier than two years in the past and not end in the future. (Limits: 4 date ranges, each date range having no more than 365/366 days)

time.timeRanges

yes

List of time ranges to analyse (Limit: 24 time ranges)

map.version

no

Optional parameter telling what map version should be used for map matching. If not used, we will pick map version for you based on selected date ranges. You can check list of available maps here. Value of this parameter should be correlated with used date range in order to avoid confusion.
map.type

no

What map type should be used. There are two possible options:
  • DSEG_NOSPLIT - this option should be used most of the time.
  • OPEN_DSEG_NOSPLIT - this option should be used when you analyse Japan region.
For details what types are currently available please refer here

Request body example

POST
Request body - JSON
1{
2 "name":"Selected Link Example",
3 "time":{
4 "dateRanges":[
5 {
6 "startDate":"2022-01-01",
7 "endDate":"2022-01-06"
8 },
9 {
10 "startDate":"2022-02-01",
11 "endDate":"2022-02-06"
12 }
13 ],
14 "daysOfWeek":[
15 "MONDAY",
16 "TUESDAY",
17 "WEDNESDAY",
18 "THURSDAY",
19 "FRIDAY",
20 "SATURDAY",
21 "SUNDAY"
22 ],
23 "timeRanges":[
24 {
25 "startTime":"08:00",
26 "endTime":"12:00"
27 },
28 {
29 "startTime":"15:00",
30 "endTime":"19:00"
31 }
32 ],
33 "zoneId":"Europe/Warsaw"
34 },
35 "link":{
36 "type":"LineString",
37 "coordinates":[
38 [
39 21.02143,
40 52.24896
41 ],
42 [
43 21.02401,
44 52.25008
45 ]
46 ]
47 },
48 "map":{
49 "version":"2022.03",
50 "type":"DSEG_NOSPLIT"
51 }
52}

All date ranges and all time ranges are multiplied to cover all possible time definitions. For above example this will result in 4 different periods:

  • 2022-01-01 - 2022-01-06 : 08:00 - 12:00
  • 2022-01-01 - 2022-01-06 : 15:00 - 19:00
  • 2022-02-01 - 2022-02-06 : 08:00 - 12:00
  • 2022-02-01 - 2022-02-06 : 15:00 - 19:00

Date range format

FieldRequiredDescription

startDate

yes

Start date of date range in YYYY-MM-DD format

endDate

yes

End date of date range in YYYY-MM-DD format

exclusions

no

List of dates to exclude from given range in YYYY-MM-DD format

Time range format

FieldDescription

startTime

Start time of time range in HH:mm format

endTime

End time of time range in HH:mm format

NOTE: To analyse a whole day you should use 00:00 for both the startTime and endTime.

Response

This response will return information about the created analysis. The table below describe all of the fields that can appear in a response.

Response structure

FieldDescription

id

Analysis number id.

name

Job name, given for user’s convenience.

owner

Email or api key of the analysis' owner

apiKey

Api key of the analysis' owner

status

Job status. One of the following values:

  • WAITING

  • RUNNING

  • ENDED

  • FAILED

  • CANCELLED

  • ACCEPTED

  • REJECTED

currentProgress

Current value of job progress (0-100)

creationTime

Job creation time in YYYY-MM-DDTHH:mm:ss.SSSZ format

timeDefinition

Time definition of the analysis.

timeDefinition.zoneId

Time zone as TZ database name. For example "Europe/Amsterdam" or "UTC"

timeDefinition.daysOfWeek

Days of week of the analysis. Allowed values:

  • MONDAY

  • TUESDAY

  • WEDNESDAY

  • THURSDAY

  • FRIDAY

  • SATURDAY

  • SUNDAY

timeDefinition.dateRanges

List of date ranges of the analysis

timeDefinition.timeRanges

List of time ranges of the analysis

tripsCounted

How many trips were counted. Updates when analysis is in progress.

startAnalysisTime

Date and time start of analysis in format: YYYY-MM-DDTHH:mm:ss.SSSZ

endAnalysisTime

Date and time end of analysis in format: YYYY-MM-DDTHH:mm:ss.SSSZ

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

HTTP Response Codes
CodeReason

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found