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. Refer to the analytics module specific API guide for the same.
Alerts API Version v2#
The Alerts API has a new major version v2 which is not backward compatible with earlier version. The previous version shipped with JPS 1.0 version is still supported in this release. However it is highly recommended to adopt/migrate to v2 version. The v2 version is provided under path /api/v2. Where the earlier version is still functional under /api.
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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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 hierarchical manner as follows:
Top level filtration by specific sensorId
Second level filtration for a specific tripwireId or and roiId
Third level filtration 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.