Alerts API Guide
Alert rules define the conditions which when meet results in generation of alerts. The type of alert rules for each analytic module (FOV, Tripwire, ROI) varies. Please refer to the analytics module specific API guide for the same.
In this section we will cover how to retrieve alerts.
Retrieve all alerts for a sensor for time range
Retrieve the alerts for a given sensor and a given time range.
HTTP GET
/api/alerts?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
Mandatory query parameters
sensorId
description: Sensors for which alerts need to be returned.
type: string.
example: sensorId=Amcrest_1
fromTimestamp
description: lower bound of the timestamp for which alerts needs to be returned
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which alert needs to be returned. If Not specified defaults to UTC.NOW on the server
type: UTC / GMT timestamp string
example: 2020-10-30T20:05:00.000Z
limit
description: max number of alerts to be returned
type: integer
example: 100
It follows Time based simple pagination. Get latest 10 (limit) alerts which occurred between 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (endTimestamp). Criteria is that endTimestamp > fromTimestamp
Example 1: All alerts between a given time range
Get all alerts between 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (toTimestamp).
/api/alerts?sensorId=Amcrest_3&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
Response:
{ "alerts": [ { "count": 10, "description": "10 people entered fov", "duration": 0.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "increment", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "entry", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 1, "description": "more than 1 ppl continuously present in FOV for longer than 10 seconds", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 5, "description": "FOV occupancy count greater than 5", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy_threshold_switch", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "up", "attributes": [] } ] }
Response body attributes
Alerts of type increment and occupancy also has in it’s attributes section the list of objects which resulted in those alerts. Each object is represented by it’s id and type. e.g id=100, type=Person.
"attributes": [ { "objects": [ { "id": 100, "type": "Person" }, { "id": 200, "type": "Person" } ] } ]
Example 2: Get latest 10 alert which occurred before a given timestamp
Get latest 10 alerts (limit=10) which occurred before 2021-09-16T06:07:00.000Z (toTimestamp).
/api/alerts?sensorId=Amcrest_3&toTimestamp=2021-09-16T06:07:00.000Z&limit=10
Example 3: Get latest 10 alert which occurred after timestamp
Get latest 10 alerts (limit=10) which occurred after 2021-09-16T06:07:00.000Z (fromTimestamp).
/api/alerts?sensorId=Amcrest_3&fromTimestamp=2021-09-16T06:07:00.000Z&limit=10
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No behavior found for the requested sensorId and time range 500: Internal server error
Error Response body
Error response for all API is JSON object with following attributes.
{
"detail": "#Detailed error string",
"status": "#http-status-code",
"title": "Unprocessable Entity",
"type": "about:blank"
}
Retrieve count of historical alerts for a sensor for time range
HTTP GET
/api/alerts/count?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
Mandatory query parameters
sensorId
description: Sensors for which alerts need to be returned.
type: string.
example: sensorId=Amcrest_1
fromTimestamp
description: lower bound of the timestamp for which alerts needs to be returned
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which alert needs to be returned. If Not specified defaults to UTC.NOW on the server
type: UTC / GMT timestamp string
example: 2020-10-30T20:05:00.000Z
limit
description: max number of alerts to be returned
type: integer
example: 100
It follows Time based simple pagination. Get latest 10 (limit) alerts which occurred between 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (endTimestamp). Criteria is that endTimestamp > fromTimestamp
Example
Get alerts count between 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (toTimestamp).
Response:
/api/alerts/count?sensorId=Amcrest_3&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
{ "alerts": [ { "sensorId": "Amcrest_3", "type": "fov", "rule_type": "increment", "rule_id": "78956", "rule_name": "lobby entry/exits", "direction": "enter", "count": 11, "attributes": [] }, { "sensorId": "Amcrest_3", "type": "tripwire", "rule_type": "increment", "rule_id": "12345", "rule_name": "main door crossings", "count": 5, "direction": "enter", "attributes": [] }, { "sensorId": "Amcrest_3", "type": "tripwire", "rule_type": "increment", "rule_id": "12345", "rule_name": "ain door crossings", "count": 2, "direction": "exit", "attributes": [] } ] }
Response body attributes
Alerts of type increment and occupancy also has in it’s attributes section the list of objects which resulted in those alerts. Each object is represented by it’s id and type. e.g id=100, type=Person.
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No behavior found for the requested sensorId and time range 500: Internal server error
Error Response body
Error response for all API is JSON object with following attributes.
{
"detail": "#Detailed error string",
"status": "#http-status-code",
"title": "Unprocessable Entity",
"type": "about:blank"
}
Notification of alerts via WebSocket endpoint
In addition the the ability to query historical alerts via the REST API /alerts there is also a websocket endpoint to get the realtime notification of alerts as they occur.
Alerts WebSocket Endpoint
Analytics Web API is exposed via Ingress Controller.
The URL prefix is http://<INGRESS-HOST-IP>:<INGRESS-PORT>/ws-emdx/api/alerts/ws.
Replace the INGRESS-HOST-IP with the Jetson device IP. Replace the INGRESS-PORT with 30080 or the last value defined in Ingress configuration.
While connecting to websocket the client can specify filter criteria for alerts which it wishes to receive. Filter criteria can be specified in a hiearchial manner as follows:
Top level filteration by specific sensorId
Second level filteration for a specific tripwireId or and roiId
Third level filteration for a specific type of alert rule.
At all levels the value of ‘*’ can be specified for a wildcard match (i.e all possible values)
[ { "sensorId": "Amcrest_1", "tripwires": [ { "tripwireId": "TW1", "alertRuleTypes": [ "increment", "flowrate" ] }, { "tripwireId": "TW2", "alertRuleTypes": [ "flowrate" ] } ], "rois": [ { "roiId": "cc1", "alertRuleTypes": [ "increment" ] }, { "roiId": "cc2", "alertRuleTypes": [ "occupancy" ] } ], "fov": { "alertRuleTypes": [ "occupancy" ] } }, { "sensorId": "Amcrest_2", "tripwires": [ { "tripwireId": "TW4", "alertRuleTypes": [ "increment", "flowrate" ] } ], "rois": [], "fov": { "alertRuleTypes": [] } } ]
Example 1: Requesting all the alerts
For each sensor notify all fov, tripwire and roi alerts.
[ { "sensorId": "*", "tripwires": [ { "tripwireId": "*", "alertRuleTypes": ["*"] } ], "rois": [ { "roiId": "*", "alertRuleTypes": ["*"] } ], "fov": { "alertRuleTypes": ["*"] } } ]
Example 2: Requesting specific alerts
For sesnor=Amcrest_1 push all tripwire and roi alerts of type increment
[ { "sensorId": "Amcrest_1", "tripwires": [ { "tripwireId": "*", "alertRuleTypes": ["increment"] } ], "rois": [ { "roiId": "*", "alertRuleTypes": ["increment"] } ], "fov": { "alertRuleTypes": [] } } ]
WebSocket Response:
The websocket response body is same the what one would receive when calling the REST API /alerts
{ "alerts": [ { "count": 10, "description": "10 people entered fov", "duration": 0.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "increment", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "entry", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 10, "description": "more than 5 ppl continuously present in FOV for longer than 10 seconds", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 5, "description": "FOV occupancy count greater than 5", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy_threshold_switch", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "up", "attributes": [] } ] }
Response body attributes
Alerts of type increment and occupancy also has in it’s attributes section the list of objects which resulted in those alerts. Each object is represented by it’s id and type. e.g id=100, type=Person.