List dwell time alert history
Deprecation notice
November 6, 2020
- The "List dwell time alert history" endpoint has been deprecated.
- This endpoint has been replaced with the generic endpoint to handle all types of Alert Rules: List alert history.
- This endpoint will be withdrawn following a 12 month deprecation period.
- The planned withdrawal date is December 1, 2021.
- Following withdrawal, requests to this endpoint may receive an HTTP 404 error in response.
- More details are available at the TomTom deprecation policy page.
Purpose
This endpoint lists Dwell Time Alerts that have been triggered in the given time range.
Request data
HTTPS method: GET
- 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.
URL format
GET
URL request example
https://{baseURL}/geofencing/{versionNumber}/alerts/dwell/history?key={Your_API_Key}&from={timestamp}&to={timestamp}&maxResults={integer}&pageNumber={integer}
curl command format
GET
Request curl command example
curl 'https://{baseURL}/geofencing/{versionNumber}/alerts/dwell/history?key={Your_API_Key}&from={timestamp}&to={timestamp}&maxResults={integer}&pageNumber={integer}'
Request parameters
The following table describes the parameters that can be used in a request.
- Required parameters must be used or the call will fail.
- Optional parameters may be used.
- The order of request parameters is not important.
Required parameters | Description |
---|---|
baseURL string | The base URL for calling the API. Value: api.tomtom.com |
versionNumber string | Service version. Value: 1 |
key string | An API Key valid for the requested service. Value: Your valid API Key . |
from timestamp | The beginning date for a listing. Value: ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss). |
Optional parameters | Description |
---|---|
to timestamp | End date for the listing. Value: ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss). |
maxResults integer | Maximum number of items returned in the response. Value: Greater than zero, less than or equal to 100. Default value: 100 |
pageNumber integer | The number of the items page to be returned in the response. The maximum number of elements on the page is equal to the maxResults value. Value: Greater than zero. Default value: 1 |
Response data
Response body
Response body - JSON
1{2 "summary": {3 "from": "ISO8601_timestamp",4 "to": "ISO8601_timestamp"5 },6 "alerts": [7 {8 "id": "uuid_string",9 "name": "name_of_the_alert",10 "object": "uuid_string",11 "fence": "uuid_string",12 "project": "uuid_string",13 "maxDwellTime": integer14 }15 ],16 "resultInfo": {17 "maxResults": integer,18 "pageNumber": integer,19 "itemsCount": integer20 }21}
Response fields
The following table describes all of the fields that can appear in a response.
Primary fields | |
---|---|
Field | Description |
summary object | Contains information about the dwell time alert history request. |
alerts array (alert) | Array of historical alerts. |
resultInfo object | Contains information about response paging. |
summary object | |
Field | Description |
from string | Timestamp (ISO 8601 format) marking the start of a period the report is generated for. |
to string | Timestamp (ISO 8601 format) marking the end of a period the report is generated for. |
alerts array | |
Field | Description |
id string | The UUID of the historical alert. |
name string | The name of the alert. |
object string | UUID of an object that triggered an alert. |
fence string | UUID of a fence that triggered an alert. |
project string | UUID of an project for which the alert was triggered. |
maxDwellTime integer | Time limit that triggered an alert. |
resultInfo object | |
Field | Description |
maxResults integer | Maximum number of items returned in the response. |
pageNumber integer | Number of the items page to be returned in the response. Maximum number of elements on the page is equal to the maxResults value. |
itemsCount integer | Number of returned items on the page. |
Response codes
Code | Meaning & possible causes |
---|---|
200 | OK |
400 | Bad Request: The value of the parameter is not a positive decimal number. |
Example
List all of the alerts triggered between 2019-08-29T01:00:00 and 2019-08-29T23:00:00.
Request format
GET
URL request example
https://api.tomtom.com/geofencing/1/alerts/dwell/history?key=PJD7y0G5AFj9Jiok6F0tIK16NiWYotb3&from=2019-08-29T01:00:00&to=2019-08-29T23:00:00&maxResults=3&pageNumber=1
Response body
Response body - JSON
1{2 "summary": {3 "from": "2019-08-29T01:00:00",4 "to": "2019-08-29T23:00:00"5 },6 "alerts": [7 {8 "id": "6141c4be-0877-4fa6-bc25-37618a80f6d3",9 "name": "Bus dwelled in bus stop for too long",10 "object": "b95ca74e-5f67-4c2d-9c80-b589fee3227a",11 "fence": "e487153c-a08f-480f-8037-a9770a9a2ab9",12 "project": "51192c51-9255-41c6-9d36-93efde94a180",13 "maxDwellTime": 30014 }15 ],16 "resultInfo": {17 "maxResults": 100,18 "pageNumber": 1,19 "itemsCount": 120 }21}