Developer

Create alert rule

Service version: 1
Last edit: 2022.09.01

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 request format

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

curl command requestformat

post
curl command requestformat
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 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.

adminKey
string

An Admin Key valid for the provided API Key.
Value: Your valid Admin Key.

POST request body

post
POST request body format - 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

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.

Response data

Response body

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

Response fields

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

Primary fields

Description

id
string

The UUID of the Alert Rule.

covers
array

The list of UUID Alerts covered by the already created Alert Rules.

Response codes

Code

Meaning & 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.

Examples

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

URL request example

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

POST body request example

post
POST body request example - 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 example

Response body example - 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.

URL request example

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

POST body request example

post
POST body request example - 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 example

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

Create a new Object Count Alert Rule.

URL request example

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

POST body request example

post
POST body request example - 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 example

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

Create a new Proximity Alert Rule

URL request example

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

POST body request format

post
POST body request 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 example

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