Sorry, you need to enable JavaScript to visit this website.
Geofencing API
Get your key

Create alert rule

 

Service version: 1
Last edit: 2021.01.19

On this page

Purpose

This endpoint is used to configure an Alert Rule.

Request data

HTTPS method: POST

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in normal text.
https://baseURL/geofencing/versionNumber/alerts/rules?key=Your_API_Key&adminKey=Your_Admin_Key

curl command

curl -v -XPOST -H "Content-type: application/json" -d
'{
   "name": "Enter name of created alert rule",
   "project": "Enter id of watched project",
   "fence": "Enter id of watched fence",
   "object": "Enter id of watched object",
   "alertType": "Enter type of alert to configure",
   "alertRuleConstraints": {
     "key": "value"
   },
   "notificationGroup": "Enter id of your notification group",
   "enabled": true
 }'
'https://baseURL/geofencing/versionNumber/alerts/rules?key=Your_API_Key&adminKey=Your_Admin_Key'

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.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
  • The order of request parameters is not important.
Required parameters
Parameter 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.
adminKey
string 		An Admin Key valid for the provided API Key.
Value: Your valid Admin Key.
Optional parameters
Note: There are no optional parameters in this endpoint.

POST request body (JSON)

{
  "name": "Enter name of created alert rule",
  "project": "Enter id of watched project",
  "fence": "Enter id of watched fence",
  "object": "Enter id of watched object",
  "alertType": "Enter type of alert to configure",
  "alertRuleConstraints": {
    "key": "value"
  },
  "notificationGroup": "Enter id of your notification group",
  "enabled": true
}

Request fields

The following table describes the fields that can be used in a request body.

Primary fields
Field Description
name
string 		The name of the Alert Rule.
Field is not required.
Default value: empty
project
string 		The UUID of the Project or * for any Project in the Configuration.
fence
string 		The UUID of the Fence or * for any Fence in the Configuration.
object
string 		The UUID of the Object or * for any Object in the Configuration.
This field is required for the "TRANSITION", "DWELL" and "PROXIMITY" Alert types.
alertType
string 		The type of the Alert Rule.
Possible values:
  • "TRANSITION": When an Object entered or exited the Fence.
  • "DWELL": When an Object stays too long inside a Fence.
  • "OBJECT_COUNT": When the limit of Objects in a Fence is exceeded.
  • "PROXIMITY": When the distance between an Object and a Fence is smaller than the provided threshold.
alertRuleConstraints{}
object 		Contains Alert constraints specific to the selected Alert Rule.
notificationGroup
string 		The UUID of the owned group in the Notification Service to send an Alert.
enabled
boolean 		The Boolean value that says if an Alert Rule is enabled or not.
Values:
  • true: An Alert is enabled.
  • false: An Alert is disabled.
Field is not required.
Default value: true
alertRuleConstraints{} object
Field Description
transitionType
string 		The type of the Transition to Alert.
Possible values:
  • "ENTER": When an Object just entered the Fence.
  • "EXIT": When an Object just exited the Fence.
  • "ALL": When an Object just entered or exited the Fence.
Required for the "TRANSITION" Alert type.
maxDwellTime
integer 		Maximum time (in seconds) that an Object can stay inside a Fence before an Alert is raised.
Required for the "DWELL" Alert type.
maxObjectCount
integer 		Maximum number of Objects that can be present in a Fence at once before an Alert is raised.
Required for the "OBJECT_COUNT" Alert type.
proximityDistance
integer 		Distance from the Fence within which the alarm will be triggered. The maximum proximity distance is 10 kilometers. Inside proximity alerts are triggered when an Object inside a Fence transitioned to a buffer area created from proximity. The value is expressed in meters.
Value: min/max: 1 to 10000.
Required for the "PROXIMITY" Alert type.
proximitySide
string 		Determines the side of the Fence from which the proximity will be measured.
Possible values:
  • "INSIDE": When proximity is supposed to be measured inside a Fence.
  • "OUTSIDE": When proximity is supposed to be measured outside a Fence.
Required for the "PROXIMITY" Alert type.

▲ Return to top

Response data

Response body

{
  "id": "Id of created alert rule",
  "covers": ["Id of covered other alert rule", "Id of covered other different alert rule"]
}

Response fields

The following table describes all of the fields that can appear in a response.

Primary fields
Field Description
id
string 		The UUID of the Alert Rule.
covers[]
array 		The list of UUID Alerts covered by the already created Alert Rules.

HTTP response codes

Code Meaning and possible causes
201 Created
400 Bad request:
  • Alert rule name is too long.
  • Object id is not provided.
  • Object id is incorrect.
  • Project id is not provided.
  • Project id is incorrect.
  • Fence id is not provided.
  • Fence id is incorrect.
  • Alert type is not provided.
  • Alert type is incorrect.
  • Notification group id is not provided.
  • Notification group id is incorrect.
Bad request for TRANSITION alert type:
  • Transition type is not provided.
  • Transition type is incorrect.
Bad request for DWELL alert type:
  • Maximum dwell time is not provided.
  • Maximum dwell time is a non-integer.
  • Maximum dwell time is negative.
Bad request for OBJECT_COUNT alert type:
  • Maximum object count is not provided.
  • Maximum object count is a non-integer.
  • Maximum object count is negative.
Bad request for PROXIMITY alert type:
  • ProximityDistance is not provided.
  • ProximityDistance is not a number.
  • ProximityDistance cannot be greater than 10000.
  • ProximityDistance cannot be smaller than 1.
  • ProximitySide is not provided.
  • ProximitySide is not a valid string value.
403 Forbidden:
  • Provided Admin Key is invalid.
  • Admin Key is missing.

▲ Return to top

Examples

Example: Create a new Transition Alert Rule for all Fences in the Configuration.

Request format

https://api.tomtom.com/geofencing/1/alerts/rules?key=PJD7y0G5AFj9Jiok6F0tIK16NiWYotb3&adminKey=b330d317-4fe1-4d48-b75f-06cc3be58fb2

POST body format

{
  "name": "Airport transition alert",
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
  "fence": "*",
  "object": "fc94720b-23cd-4ddf-a560-00f8518e43c9",
  "alertType": "TRANSITION",
  "alertRuleConstraints": {
    "transitionType": "ALL"
  },
  "notificationGroup": "358a3348-26d6-4d9d-8d5a-c3de41b26f63",
  "enabled": true
}

Response body

{
  "id": "bf40406b-1d8d-4218-bcf2-e67b83063d02",
  "covers": []
}

Example: Create a new Dwell Time Alert Rule for all Objects in the Configuration.

Request format

https://api.tomtom.com/geofencing/1/alerts/rules?key=PJD7y0G5AFj9Jiok6F0tIK16NiWYotb3&adminKey=b330d317-4fe1-4d48-b75f-06cc3be58fb2

POST body format

{
  "name": "24-hour parking #5 alert",
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
  "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
  "object": "*",
  "alertType": "DWELL",
  "alertRuleConstraints": {
    "maxDwellTime": 600
  },
  "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
  "enabled": true
}

Response body

{
  "id": "a5e0e694-851e-4b6e-9c35-0dee908165c1",
  "covers": ["c30520d9-e5bc-4522-8e4b-02e595e4784c", "8378399e-169e-4963-a22d-950e137ae1ef"]
}

Example: Create a new Object Count Alert Rule.

Request format

https://api.tomtom.com/geofencing/1/alerts/rules?key=PJD7y0G5AFj9Jiok6F0tIK16NiWYotb3&adminKey=b330d317-4fe1-4d48-b75f-06cc3be58fb2

POST body format

{
  "name": "City ​​parking #7 with a capacity of 20 cars",
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
  "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
  "alertType": "OBJECT_COUNT",
  "alertRuleConstraints": {
    "maxObjectCount": 20
  },
  "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
  "enabled": true
}

Response body

{
  "id": "f19df201-09f1-4ac2-84ce-913658c32c2e",
  "covers": ["303cc7cf-038e-420a-b14a-e9f52fbf741e"]
}

Example: Create a new Proximity Alert Rule.

Request format

https://api.tomtom.com/geofencing/1/alerts/rules?key=PJD7y0G5AFj9Jiok6F0tIK16NiWYotb3&adminKey=b330d317-4fe1-4d48-b75f-06cc3be58fb2

POST body format

{
  "name": "Driver is approaching the end of the safety zone",
  "project": "47b10143-0b43-4803-a931-98cb1e595520",
  "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
  "object": "*",
  "alertType": "PROXIMITY",
  "alertRuleConstraints": {
    "proximityDistance": 1000,
    "proximitySide": "OUTSIDE"
  },
  "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
  "enabled": true
}

Response body

{
  "id": "274c7ff0-8030-4b67-a239-aa9f62cefef0",
  "covers": []
}

▲ Return to top