Area Analysis
The Area Analysis API calculates statistics for an area. 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 length of date range is 366 days.
- The maximum number of time sets is 24.
- Network size, calculated as size of bounding box of defined geometry, cannot be greater than 20 000 km².
- 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/areaanalysis/<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 | Parameter | Req'd? | Type / Values | Default Value |
---|---|---|---|---|
jobName | Job name. Given for user's convenience. | Yes | String | — |
distanceUnit | Base unit used for distance and speed. | Yes |
|
— |
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 network, 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 | — |
network | Network for calculations. See structure here. | Yes | Object | — |
dateRange | Range of dates for calculations. See structure here. | Yes | Object | — |
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 network
Parameter | Parameter | Req'd? | Type / Values | Default Value |
---|---|---|---|---|
name | Name of the network. | Yes | String | — |
timeZoneId | In which time zone all times are given. | Yes | String Time zone like: "Europe/Amsterdam" or "UTC". See time zone names from tz database for more. |
— |
frcs | Functional road classes. | Yes | List of Integers from range 0-8 | — |
probeSource | Determines from what devices data will be used. Possible values:
|
No | String ALL, PASSENGER, TELEMATICS |
PASSENGER |
geometry | Geometry of the network in GeoJSON format. Supported geometry types are Polygon and MultiPolygon. See RFC 7946 | Yes | Object | — |
boundingBox | Bounding box of the network. Mutually exclusive with geometry. Deprecated, please use geometry. | No | Object | — |
Structure of dateRange
Parameter | Parameter | Req'd? | Type / Values | Default Value | |
---|---|---|---|---|---|
name | Date range name. Given for user's convenience. | Yes | String | — | |
from | Date from (inclusive) | Yes | Date in format: YYYY-MM-DD | — | |
to | Date to (inclusive) | 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:
|
|
Structure of timeSets
Parameter | Parameter | Req'd? | Type / Values | Default Value |
---|---|---|---|---|
name | Time set name. Given for user's convenience. | Yes | String | — |
timeGroups | Time groups in time set
|
Yes | List | — |
JSON example request
{ "jobName":"Test job", "distanceUnit":"KILOMETERS", "network": { "name": "test", "geometry" : { "type": "MultiPolygon", "coordinates": [ [ [ [19.44305, 51.75612], [19.44992, 51.75612], [19.44992, 51.75947], [19.44305, 51.75947], [19.44305, 51.75612] ] ], [ [ [19.45011, 51.75789], [19.45687, 51.75789], [19.45687, 51.75946], [19.45011, 51.75946], [19.45011, 51.75789] ] ] ] }, "timeZoneId": "Europe/Warsaw", "frcs": [ "0", "1", "2", "3", "4", "5", "6", "7", "8" ], "probeSource":"ALL" }, "dateRange": { "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":"677","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. |
SCHEDULED | Reserved for future use. |
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. |
NEED_CONFIRMATION | Reserved for future use. |
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, bounding box cannot be processed (it is effectively empty because there are no roads with selected frcs or it is defined 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_json_result_file>","<url_for_geojson_result_file>","<url_for_shape_result_file>"]}
Results
Output of Area Analysis is available in JSON, GeoJSON and SHAPE format. JSON and GeoJSON results are provided in a gzip compressed format. 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
|
Object |
dateRanges | (from request)
|
List |
timeSets | (from request) See structure here. | List |
network | Data for requested network. See structure here. | Object |
Structure of timeSets
Field(s) | Description | Type / Values |
---|---|---|
@id | Helper reference for further use (in network.segmentResults.segmentTimeResults). | Integer |
name | (from request) | (as in request) |
dayToTimeRanges | Time ranges from request grouped per day of week:
|
List |
Structure of network
Field(s) | Description | Type / Values |
---|---|---|
networkName, zoneId, probeSource | (from request) | (as in request) |
mapsVersions | Version of maps used for map matching. | String |
segmentResults | Data for each segment in given area. 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 |
harmonicAverageSpeed | Harmonic average speed (in kmph or mph according to userPreference). | Float |
medianSpeed | Median speed (in kmph or mph according to userPreference). | Float |
averageSpeed | Average speed (in kmph or mph according to userPreference). | Float |
standardDeviationSpeed | Standard deviation of speed (in kmph or mph according to userPreference). | Float |
travelTimeStandardDeviation | Standard deviation of travel time (in seconds). | 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 |
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 (in kmph or mph according to userPreference). | List of 19 Integers |