Sorry, you need to enable JavaScript to visit this website.

Route Analysis

The Route Analysis API calculates a statistics for a defined route between an origin and a destination, optionally via waypoints. This API is asynchronous. There are two endpoints consuming two types of requests. The first one is only for ordering jobs with POST requests. In its response the user receives a jobId, which should be used in the second endpoint with GET request to the check job's status. When job is successfully finished user in response will receive links to download results.

There are some important notes about using this API:

  • The latitude and longitude coordinates are in EPSG4326 / WGS84 format for both input and output. Other coordinate systems are not supported.
  • All averages are calculated arithmetically unless otherwise stated (example JSON field: harmonicAverageSpeed is calculated harmonically).
  • The current API version is 1.
  • The maximum route length is 200 kilometers. Routes longer than this will be rejected.
  • The maximum number of routes is 20.
  • The maximum number of date ranges is 24.
  • The maximum number of time sets is 24.
  • When you define a route you should consider to use via points. Without via points there is no guarantee that the route the Online Routing engine is using is the route you want to measure.
  • As the service is asynchronous it can take a while before results are available, depending on how busy the service is. Do not repost your request multiple times if you do not get feedback within seconds, we will ensure that the results are delivered.
  • At the same time you can have only 5 jobs in MAPMATCHED and READING_GEOBASE statuses per each developer key. When you reach this limit you can still create new jobs as they will be queued until at least one of currently running jobs is done.

Request

Format

https://<baseURL>/traffic/trafficstats/routeanalysis/<versionNumber>?key=<apiKey>

Required POST Headers

Content-Type: application/json

Parameters

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters may be used.

Parameter Description Req'd? Type / Values Default Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 1. Yes 1
apiKey Authorization key for access to the API. Yes API Key

JSON request parameters

Below JSON parameters refer to POST request.

Parameter Description Req'd? Type / Values Default Value
jobName Job name which will be used in the process and output. Given for user's convenience. Yes String
distanceUnit Base unit used for distance and speed values. Yes
  • KILOMETERS
  • MILES
mapVersion What map should be used. List of currently available maps in all Traffic Stats APIs can be checked here. No String 2016.12
averageSampleSizeThreshold If average sample size for any combination of route, date range and time set will be lower than given value then output will not be generated, job will be moved into REJECTED state and user will not be charged for such report. If not specified output will be always generated no matter how many samples were available. No Integer
routes Routes for calculations. See structure here. Yes List
dateRanges Ranges of dates for calculations. Limit the date range to maximum one year in order to restrict the processing time. See structure here. Yes List
timeSets Time sets for calculations. The first time set is a "Base Set" and every other time set will be compared to it in the output (example JSON field: travelTimeRatio). See structure here. Yes List

Structure of routes

Parameter Description Req'd? Type / Values Default Value
name Name of the route. Given for user's convenience. Yes String
start Point where the route starts

  • latitude - Latitude of start point (required)
  • longitude - Longitude of start point (required)
Yes Longitude & latitude
via List of points through which the route should go

  • latitude - Latitude of start point (required)
  • longitude - Longitude of start point (required)
No List of pairs: longitude & latitude
end Point where the route ends

  • latitude - Latitude of end point (required)
  • longitude - Longitude of end point (required)
Yes Longitude & latitude
fullTraversal When you only want vehicles that traversed the full route taken into account you need to use this parameter. Yes Boolean
zoneId In which time zone all times are given. Yes Time zone like: "Europe/Amsterdam" or "UTC"
probeSource Determines from what devices data will be used.
Possible values:

  • PASSENGER - Passenger Vehicles
  • TELEMATICS - Fleet Management Vehicles
  • ALL - All Vehicles (Passenger and Fleet combined)
No String
ALL, PASSENGER, TELEMATICS
PASSENGER

Structure of dateRanges

Parameter Description Req'd? Type / Values Default Value
name Date range name. Given for user's convenience. Yes String
from Date from Yes Date in format: YYYY-MM-DD
to Date to Yes Date in format: YYYY-MM-DD
exclusions List of days excluded from date range No List of dates in format: YYYY-MM-DD
excludedDaysOfWeek List of days of week to be excluded No

List of values:

  • MON
  • TUE
  • WED
  • THU
  • FRI
  • SAT
  • SUN

Structure of timeSets

Parameter Description Req'd? Type / Values Default Value
name Time set name. Given for user's convenience. Yes String
timeGroups Time groups in time set

  • days - Days of week for time group (required)

    list of values:

    • MON
    • TUE
    • WED
    • THU
    • FRI
    • SAT
    • SUN
  • times - Time ranges for time group, list of values in format: HH:mm-HH:mm (required)
Yes List

JSON example request

{
  "jobName":"Test job",
  "distanceUnit":"KILOMETERS",
  "routes":[
    {
      "name":"Some Route",
      "start":{
        "latitude":51.7822,
        "longitude":4.61689
      },
      "via":[
        {
          "latitude":51.78153,
          "longitude":4.60559
        }
      ],
      "end":{
        "latitude":51.78555,
        "longitude":4.61076
      },
      "fullTraversal":false,
      "zoneId":"Europe/Amsterdam",
      "probeSource":"ALL"
  }
  ],
  "dateRanges":[
    {
      "name":"Last working week of April",
      "from":"2015-04-24",
      "to":"2015-04-30",
      "exclusions":[
        "2015-04-25",
        "2015-04-26"
      ]
    }
  ],
  "timeSets":[
    {
      "name":"Monday morning hour",
      "timeGroups":[
        {
          "days":[
            "MON"
          ],
          "times":[
            "7:00-8:00"
          ]
        }
      ]
    }
  ]
}

Response

In response to the request a jobId is provided, which is required for further communication about the query. A JSON response content example:

{"jobId":"678","responseStatus":"OK","messages":["Job created. Processing started."]}

Check job status

When a job has been initiated via the API request it is possible to check the status.

JSON request

https://<baseURL>/traffic/trafficstats/status/<versionNumber>/<job_id>?key=<apiKey>

Parameters

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters may be used.

Parameter Description Req'd? Type / Values Default Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 1. Yes 1
apiKey Authorization key for access to the API. Yes API Key

JSON response

{"jobId":"<job_id>","jobState":"<job_status>","responseStatus":"OK"}

Job status flow

During the process there are different stages applicable. Via the get state request you can see what the state of your job is. Below you find the different stages of the process.

Status Description
NEW The job is waiting for mapmatching to start.
MAPMATCHING Mapmatching is in progress.
MAPMATCHED Mapmatching is done and the job is waiting for Geobase reading. 
READING_GEOBASE Geobase reading is in progress.
CALCULATIONS Calculations are in progress.
DONE Calculations are done. The results are waiting to be downloaded.
ERROR The job stopped due to the fact that something went wrong. This can occur at any place in the flow.   
REJECTED The job is rejected. During processing it turned out that job exceeds set limits, at least one of routes cannot be processed (route between points cannot be generated or is on area which is not supported) or there is less samples then required (see averageSampleSizeThreshold). This can occur at any place in the flow.
EXPIRED The job is older than a year and all data has been removed.

Response and Results

Final DONE response

{"jobId":"<job_id>","jobState":"DONE","responseStatus":"OK","urls":["<url_for_xlsx_result_file>","<url_for_json_result_file>","<url_for_geojson_result_file>","<url_for_kmz_result_file>","<url_for_shape_result_file>"]}

Results

Output of Route Analysis is available in XLSX, JSON, GeoJSON, KMZ and SHAPE formats. JSON results are provided in a gzip compressed format. GeoJSON and SHAPE files are packed into zip archives. If you want to get an example of these files please click on the applicable names.

JSON result description

Field(s) Description Type / Values
jobName (from request) (as in request)
creationTime Job creation time. Timestamp in format: yyyy-MM-ddTHH:mm:ss.SSSZ
userPreference Requested preference

  • distanceUnit - (as in request)
Object
dateRanges (from request)

  • @id - Helper reference for further use
    (in routes.segmentResults.segmentTimeResults)
  • name, from, to, exclusions - as in request
  • excludedDaysOfWeek - as in request, value from: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
List
timeSets (from request) See structure here. List
routes Data for each requested segment. See structure here. List

Structure of timeSets

Field(s) Description Type / Values
@id Helper reference for further use (in routes.segmentResults.segmentTimeResults). Integer
name (from request) (as in request)
dayToTimeRanges Time ranges from request grouped per day of week:

  • dayOfWeek - Day of week for time group, value from: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
  • timeRanges - Time ranges for time group, list of values in format: HH:mm-HH:mm
List

Structure of routes

Field(s) Description Type / Values
routeName, zoneId, fullTraversal, probeSource (from request) (as in request)
mapsVersions Version of maps used for map matching. String
segmentResults Data for each segment in given route. See structure here. List
summaries Summary reports for each calculated date range-time set pair for the whole route. See structure here. List

Structure of segmentResults

Field(s) Description Type / Values
segmentId Segment id. Integer
newSegmentId New segment id. String
speedLimit Speed limit (in kmph or mph according to userPreference). Integer
frc Functional Road Class. Integer (0-8)
streetName Street name. String
distance Length of segment (in meters or feet according to userPreference). Float
shape Geometrical shape of segment. List of pairs: longitude & latitude
segmentTimeResults Calculated time data for given segment. See structure here. List

Structure of segmentTimeResults

Field(s) Description Type / Values
timeSet Reference to TimeSet in which calculations were made. Integer
dateRange Reference to DateRange in which calculations were made. Integer
medianSpeed Median speed (in kmph or mph according to userPreference). Float
sampleSize The sample size visible on the segment. These are unique vehicles traveling on segment.  If several measurements are received from the same vehicle on a single segment it is only counted once in the sample size count. Integer
averageTravelTime Average travel time (in seconds). Float
medianTravelTime Median travel time (in seconds). Float
travelTimeStandardDeviation Travel time standard deviation (in seconds). Float
travelTimeRatio Ratio of travel time in current TimeSet to travel time in Base Set (first TimeSet and same DateRange). Float
speedPercentiles Percentile speeds in ascending order: 5th, 10th, ... 90th, 95th. List of 19 Integers
averageSpeed Average speed (in kmph or mph according to userPreference). Float
harmonicAverageSpeed Harmonic average speed (in kmph or mph according to userPreference). Float
standardDeviationSpeed Standard deviation speed (in kmph or mph according to userPreference). Float

Structure of summaries

Field(s) Description Type / Values
dateRange Reference to DateRange in which calculations were made. Integer
timeSet Reference to TimeSet in which calculations were made. Integer
distance Length of whole route (in meters or feet according to userPreference). Float
coveredDistance Summary length of segments covered with data (as above). Float
averageSampleSize The total sample size divided by the amount of segments. These are unique vehicles traveling on each segment in each time period.  If several measurements are received from the same vehicle on a single segment it is only counted once in the sample size count. Float
harmonicAverageSpeed Harmonic average speedfor the complete route. Float
averageTravelTime Average travel time for the complete route. Float
medianTravelTime Median travel time for the complete route. Float
travelTimeStandardDeviation Travel time standard deviation (in seconds). Only for full traversal routes. Float
averageTravelTimeRatio Ratio of average travel time in current TimeSet to average travel time in Base Set (first TimeSet and same DateRange). Float
planningTimeIndex Ratio of 95th travel time percentile in current TimeSet to average travel time in Base Set (first TimeSet and same DateRange). Float
travelTimePercentiles Percentile travel time in ascending order: 5th, 10th, ... 90th, 95th. List of 19 Floats
speedPercentiles Percentile speeds in ascending order: 5th, 10th, ... 90th, 95th. List of 19 Floats

You are here