Create alert rule

Service version: 1
Last edit: 2022.07.22

Purpose

This endpoint is used to configure an Alert Rule.

Request data

HTTPS method: POST

  • 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

POST
URL request example
https://{baseURL}/geofencing/{versionNumber}/alerts/rules?key={Your_API_Key}&adminKey={Your_Admin_Key}

curl command format

POST
Request curl command example
1curl -v -XPOST -H "Content-type: application/json" -d
2'{
3 "name": "Enter name of created alert rule",
4 "project": "Enter id of watched project",
5 "fence": "Enter id of watched fence",
6 "object": "Enter id of watched object",
7 "alertType": "Enter type of alert to configure",
8 "alertRuleConstraints": {
9 "key": "value"
10 },
11 "notificationGroup": "Enter id of your notification group",
12 "enabled": true
13 }'
14'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.
  • The order of request parameters is not important.

Note: There are no optional parameters in this endpoint.

Required parametersDescription
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.

POST request body

POST
POST request body example - JSON
1{
2 "name": "Enter name of created alert rule",
3 "project": "Enter id of watched project",
4 "fence": "Enter id of watched fence",
5 "object": "Enter id of watched object",
6 "alertType": "Enter type of alert to configure",
7 "alertRuleConstraints": {
8 "key": "value"
9 },
10 "notificationGroup": "Enter id of your notification group",
11 "enabled": true
12}

POST request body fields

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

Primary fields
FieldDescription
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
FieldDescription
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.

Response data

Response body

Response body - JSON
1{
2 "id": "Id of created alert rule",
3 "covers": ["Id of covered other alert rule", "Id of covered other different alert rule"]
4}

Response fields

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

Primary fieldsDescription
id
string
The UUID of the Alert Rule.
covers
array
The list of UUID Alerts covered by the already created Alert Rules.

Response codes

CodeMeaning & possible causes
201Created
400Bad 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.
403Forbidden:
  • Provided Admin Key is invalid.
  • Admin Key is missing.

Examples

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

Request format

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

POST body format

POST
POST body format - JSON
1{
2 "name": "Airport transition alert",
3 "project": "47b10143-0b43-4803-a931-98cb1e595520",
4 "fence": "*",
5 "object": "fc94720b-23cd-4ddf-a560-00f8518e43c9",
6 "alertType": "TRANSITION",
7 "alertRuleConstraints": {
8 "transitionType": "ALL"
9 },
10 "notificationGroup": "358a3348-26d6-4d9d-8d5a-c3de41b26f63",
11 "enabled": true
12}

Response body

Response body - JSON
1{
2 "id": "bf40406b-1d8d-4218-bcf2-e67b83063d02",
3 "covers": []
4}

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

Request format

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

POST body format

POST
POST body format - JSON
1{
2 "name": "24-hour parking #5 alert",
3 "project": "47b10143-0b43-4803-a931-98cb1e595520",
4 "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
5 "object": "*",
6 "alertType": "DWELL",
7 "alertRuleConstraints": {
8 "maxDwellTime": 600
9 },
10 "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
11 "enabled": true
12}

Response body

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

Create a new Object Count Alert Rule.

Request format

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

POST body format

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

Response body

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

Create a new Proximity Alert Rule

Request format

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

POST body format

POST
POST body format - JSON
1{
2 "name": "Driver is approaching the end of the safety zone",
3 "project": "47b10143-0b43-4803-a931-98cb1e595520",
4 "fence": "0b16633b-7b2b-4fd6-a834-f36c2250ab66",
5 "object": "*",
6 "alertType": "PROXIMITY",
7 "alertRuleConstraints": {
8 "proximityDistance": 1000,
9 "proximitySide": "OUTSIDE"
10 },
11 "notificationGroup": "8e34613a-2324-4749-ac9d-25bf7a91d218",
12 "enabled": true
13}

Response body

Response body - JSON
1{
2 "id": "274c7ff0-8030-4b67-a239-aa9f62cefef0",
3 "covers": []
4}