Analysis Creation

Service version: 1
Last edit: 2022.08.22

Purpose

Create a Selected Link Analysis by sending a POST request.

Request data

HTTPS Method: POST

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

Format

POST
URL request format
https:/{baseURL}/origindestination/{versionNumber}/analysis/selected-link?key={Your_API_Key}

Example

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

Request 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.
key
string
Authorization key for access to the API.
Value: Your valid API Key.

Request POST body structure

Required fieldsDescription
name
string
Job name string which will be used in the process and output. Given for the user’s convenience.
link
string
GeoJSON LineString is the correct definition of a link. (Limit: Maximum length of a link is 10 km.)
time
object
Time definition for the analysis.
time.zoneId
string
Time zone for the analysis as a TZ database name. For example "Europe/Amsterdam" or "UTC".
time.daysOfWeek
array (of strings)
Days of the week to analyse. Allowed values:
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY
time.dateRanges
array (of dates)
List of date ranges to analyze. 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
array (of times)
List of time ranges to analyse (Limit: 24 time ranges).
Optional fieldsDescription
map.version
float
Optional parameter telling what map version should be used for map matching. If not used, we will pick a map version for you based on the selected date ranges. You can check the list of available maps at Available Maps. The value of this parameter should be correlated with the used date range in order to avoid confusion.
map.type
string
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 the Japan region.

For details what types are currently available, please refer to Available Maps.

Required POST headers

HeaderValue
Content-Typeapplication/json

Request POST 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 the preceding 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

Required fieldsDescription
startDate
string
Start date of the date range in YYYY-MM-DD format.
endDate
string
End date of the date range in YYYY-MM-DD format.
Optional fieldsDescription
exclusions
array (of dates)
List of dates to exclude from the given range in YYYY-MM-DD format.

Time range format

FieldDescription
startTime
string
Start time of the time range in HH:mm format.
endTime
string
End time of the time range in HH:mm format.

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

Response data

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

Response structure

FieldDescription
id
integer
Analysis number id.
name
string
Job name, given for the user’s convenience.
owner
string
Email or API Key of the analysis' owner.
key
string
API Key of the analysis' owner.
status
string
Job status. One of the following values:
  • WAITING
  • RUNNING
  • ENDED
  • FAILED
  • CANCELLED
  • ACCEPTED
  • REJECTED
currentProgress
integer
Current value of the job progress (0-100).
creationTime
datetime
Job creation time in YYYY-MM-DDTHH:mm:ss.SSSZ format.
timeDefinition
string
Time definition of the analysis.
timeDefinition.zoneId
string
Time zone as a TZ database name. For example "Europe/Amsterdam" or "UTC".
timeDefinition.daysOfWeek
string
Days of the week of the analysis. Allowed values:
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY
timeDefinition.dateRanges
array
List of date ranges of the analysis.
timeDefinition.timeRanges
array
List of time ranges of the analysis.
tripsCounted
integer
How many trips were counted. Updates when the analysis is in progress.
startAnalysisTime
datetime
Date and time start of the analysis in format: YYYY-MM-DDTHH:mm:ss.SSSZ.
endAnalysisTime
datetime
Date and time end of the 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.

Response codes

CodeMeaning & possible causes
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found