Field of view (FOV) API Guide
FOV Counts, Alerts and Alert Rule are accessible via the Web API.
FOV API Endpoints
Analytics Web API is exposed via Ingress Controller.
The URL prefix is http://<INGRESS-HOST-IP>:<INGRESS-PORT>/emdx/.
Replace the INGRESS-HOST-IP with the Jetson device IP. Replace the INGRESS-PORT with 30080 or the last value defined in Ingress configuration.
FOV Counts
Retrieve FOV counts histogram
Histogram of count of people in camera field of view for a given time range and a specified fixed interval
HTTP GET
/api/metrics/occupancy/fov/histogram?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z
Mandatory query parameters
sensorId
description: Sensors for which FOV metrics need to be returned.
type: string.
example: sensorId=Amcrest_1
fromTimestamp
description: lower bound of the timestamp for which fov count needs to be returned.
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which fov count & 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
Optional query parameters
alerts
description: Enable alerts data in the results.
type: boolean
If parameter is true, return alerts for the requested duration in the response. If parameter is absent or false, alerts are not returned as part of the response.
fixedInterval
description : Requested time range (fromTimestamp - toTimestamp) fragmented into histogram of interval fixedInterval milliseconds. Minimum value of 1000 milli sec (1sec). Multiple of 1000 milli sec (1 sec) values only supported.
type: int
Limitation: If the number of histogram in the result exceeds 1000, the API will result in error with status 422.
If this parameter is not specified the service will decide the time interval of histogram based on the configuration values metrics.fov.barCount.[min, max]. The number of histogram returned will be an average of the min and max value. Accordingly the interval will be decided as follows
interval = (toTimestamp-fromTimestamp) / ((metrics.fov.barCount.min+metrics.fov.barCount.max)/2)
objectTypes
description: An optional objectTypes parameter used to breakdown histogram counts by object type (e.g People, Vehicle,…)
type: string
Possible way to breakdown counts by object type is as follows
1) To return counts for only specific type of objects in addition to cumulative counts across all types of objects. objectTypes=People,Vehicle
2) To return counts for all object types in addition to cumulative counts across all types of objects. objectTypes=*
When objectTypes is not specified it returns only cumulative counts across all types of objects.
Response
{ "alerts": [], "counts": [ { "agg_window": "2 sec", "histogram": [ { "end": "2020-01-26T19:16:30.000Z", "start": "2020-01-26T19:16:29.000Z", "avg_count": 1, "min_count": 0, "max_count": 2 }, { "end": "2020-01-26T19:17:29.000Z", "start": "2020-01-26T19:17:28.000Z", "avg_count": 1.5, "min_count": 1, "max_count": 3 } ], "attributes": [], "sensorId": "Amcrest_1", "type": "fov_count" } ], "object_type_counts": { "Person":[ { "agg_window": "2 sec", "histogram": [], "attributes": [], "sensorId": "Amcrest_1", "type": "fov_count" } ], "Vehicle":[ { "agg_window": "2 sec", "histogram": [], "attributes": [], "sensorId": "Amcrest_1", "type": "fov_count" } ] } }
Response body attributes
counts
description: Histogram of cumulative counts across all types of objects (e.g People, Vehicle,…)
type: Array of object
object_type_counts
description: Breakdown of historam of counts by object type (e.g People, Vehicle,…)
type: Dictionary of object type (key) to histogram counts (value) elements.
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No FOV metrics found for the requested sensor and time range 500: Internal server error
Example
Query FOV counts for 5 minutes time range and aggregate the results into 10sec non-overlapping fixed interval.
HTTP GET
/api/metrics/occupancy/fov/histogram?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z&fixedInterval=10
Retrieve FOV total counts
Total count of people in camera field of view for a given time range.
HTTP GET
/api/metrics/occupancy/fov/count?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z
Mandatory query parameters
sensorId
description: Sensors for which FOV metrics need to be returned.
type: string.
example: sensorId=Amcrest_1
fromTimestamp
description: lower bound of the timestamp for which fov count needs to be returned.
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which fov count & 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
Optional query parameters
objectTypes
description: An optional objectTypes parameter used to breakdown counts by object type (e.g People, Vehicle,…)
type: string
Possible way to breakdown counts by object type is as follows
1) To return counts for only specific type of objects in addition to cumulative counts across all types of objects. objectTypes=People,Vehicle
2) To return counts for all object types in addition to cumulative counts across all types of objects. objectTypes=*
When objectTypes is not specified it returns only cumulative counts across all types of objects.
Response
{ "counts": [ { "total_count": 10 "attributes": [], "sensorId": "Amcrest_1" "count_by_type": { "Person": 3, "Vehicle": 2 } } ] }
Response body attributes
counts.total_count
description: Cumulative counts across all types of objects (e.g People, Vehicle,…)
type: integer
counts.count_by_type
description: Breakdown of counts by object type (e.g People, Vehicle,…)
type: Dictionary of object type (key) to counts (value) elements.
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No FOV metrics found for the requested sensor and time range 500: Internal server error
Example
Query FOV total count for 5 minutes time range.
/api/metrics/occupancy/fov/count?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z
FOV Alerts
Retrieve FOV Alerts
FOV Alerts can be retrieved using the API which has filtering for sensor, time ranges with optional support for time based pagination
HTTP GET
/api/alerts/fov?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 FOV metrics need to be returned.
type: string.
example: sensorId=Amcrest_1
fromTimestamp
description: lower bound of the timestamp for which fov 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 fov 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 all alerts between 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (toTimestamp).
HTTP GET
/api/alerts/fov?sensorId=Amcrest_1&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": 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.
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No FOV alerts found for the requested sensor and time range 500: Internal server error
Get all latest 10 (limit) alerts between 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (toTimestamp).
HTTP GET:
/api/alerts/fov?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z&limit=10
Configure FOV alert rules
Three types of alerts rules i.e., Increment, Occupancy, Occupancy Threshold Switch are supported.
Occupancy alert type
Alert when count_threshold of people present in the ROI continuously for longer than time_interval seconds
Example: Alert rule to raise an alert when 100 or more people are continuously present in the FOV for more than 10 seconds.
HTTP POST
/api/config/rule/alerts/fov{ "sensorId": "Amcrest_1", "rules": [ { "rule_id": "d8f0484f-b464-4a92-a5a9-649a14160b53", "id": "Amcrest_1", "type": "fov", "rule_type": "occupancy", "name": "Overcrowding scenario rule", "time_interval": 10, "count_threshold": 100 } ] }
Mandatory body parameters
sensorId
description: Sensors for which alert rule is to be created.
type: string
example: Amcrest_1
rules
description: array of alert rules.
type: array
example:
{ "rule_id": "cd2218f6-e4d2-4ad4-9b15-3396e4336064", "id": "Amcrest_1", "name": "Over crowding scenario rule", "type": "fov", "rule_type": "occupancy", "time_interval": 10, "count_threshold": 100 }
Each alert rule consists of following parameters:
Mandatory rule parameters
rule_id
description: Unique ID for this alert rule. This should be unique across all alert rules
type: string
example: UUID e.g cd2218f6-e4d2-4ad4-9b15-3396e4336064
id
description: Refers to the FOV for which alert rule applies. Since FOV are not required to be explicitly configured. This can contain the name of the sensor itself for FOV alert rule.
type: string
example: Amcrest_1
type
description: Type of analytics module this alert relates to. Fixed value ‘fov’
type: string
example: fov
rule_type
description: Type of alert rule. Fixed value ‘occupancy’
type: string
value: occupancy
time_interval
description: Time window. Specified in seconds.
type: float
example: 10
count_threshold
description: Threshold on Number of counts.
type: int
example: 100
Optional rule parameters
- name
description: User friendly name for the alert rule. For display purpose on the client side
type: string
example: “Over crowding scenario rule”
Note
You will need to set User-Type=Admin in the HTTP header of the HTTP POST request.
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 500: Internal server error
Occupancy threshold switch alert type
Alerts based on change of occupancy above or below count_threshold of detected objects present in the field. Most simple use case is when FOV status changes from vacant (occupancy == 0) to occupied (occupancy >= 1). The inverse of this is when occupancy changes from occupied (occupancy >= 1) to vacant ( occupancy == 0).
HTTP POST
/api/config/rule/alerts/fov{ "sensorId": "Amcrest_1", "rules": [ { "rule_id": "ae511b25-a57d-483f-b4c5-c30e039cc375", "id": "Amcrest_1", "type": "fov", "rule_type": "occupancy_threshold_switch", "time_interval": 1, "count_threshold": 1, "parameters": [ { "name":"time_interval_up", "value":1, }, { "name":"time_interval_down", "value":2, } ] } ] }
Mandatory body parameters
sensorId
description: Sensor for which FOV alert rule is to be created.
type: string
example: Amcrest_1
rules
description: array of alert rules.
type: array.
example:
{ "rule_id": "ae511b25-a57d-483f-b4c5-c30e039cc375", "id": "Amcrest_1", "type": "fov", "rule_type": "occupancy_threshold_switch", "time_interval": 1, "count_threshold": 1, "parameters": [ { "name":"time_interval_up", "value":1, }, { "name":"time_interval_down", "value":2, } ] }
Alert Rule
Each alert rule consists of following parameters:
Mandatory rule parameters
rule_id
description: Unique ID for this alert rule. This should be unique across all alert rules
type: string
example: UUID e.g ae511b25-a57d-483f-b4c5-c30e039cc375
id
description: Refers to the FOV for which alert rule applies. Since FOV are not required to be explicitly configured. This can contain the name of the sensor itself for FOV alert rule.
type: string
example: Amcrest_1
type
description: Type of analytics module. Fixed value ‘fov’
type: string
value: fov
rule_type
description: Type of alert rule. Fixed value ‘occupancy_threshold_switch’
type: string
value: occupancy_threshold_switch
time_interval
description: Time window. Specified in seconds. Indicate the duration for which the counts needs to above or below the threshold for the alert to be raised. It is used to deal jitters in occupancy counts and smoothen the publication of alerts in case of such jitters.
type: float
example: 1
count_threshold
description:
Number of counts threshold used to determine status
count_threshold of zero indicates alert to be raised when occupancy changes from zero to greater than zero. Inverse of this is when occupancy falls to zero from a positive number greater than zero then an alert is raised.
positive non-zero count_threshold (N) means we want to raise alert when occupancy exceeds N raise the UP alert (direction=up) while when the occupancy falls to N or below raise the DOWN (direction=down) alert.
type: int
example: 1
Optional rule parameters
parameters
description: Rule specific parameters, specified as an array of name, value pairs.
type: array of name, value pairs
example: Following is the valid parameters supported by occupancy_threshold_switch alert type
parameters: [ { "name":"time_interval_up", "value":1, }, { "name":"time_interval_down", "value":2, } ]time_interval_up: The time interval for vacant to occupied state change
time_interval_down: The time interval for occupied to vacant state change
- name
description: User friendly name for the alert rule. For display purpose on the client side
type: string
example: “Over crowding scenario rule”
Note
You will need to set User-Type=Admin in the HTTP header of the HTTP POST request.
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 500: Internal server error
Increment alert rule type
Alerts based on count_threshold of object entered/exited in the field of view within time_interval seconds.
Create a new alert rule
HTTP POST
/api/config/rule/alerts/fov{ "sensorId": "Amcrest_1", "rules": [ { "rule_id": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "id": "Amcrest_1", "type": "fov", "rule_type": "increment", "time_interval": 1, "count_threshold": 1, "direction": "entry" }, { "rule_id": "9c5632af-ba68-46bc-a997-858bdadc6856", "id": "Amcrest_1", "type": "fov", "rule_type": "increment", "time_interval": 5, "count_threshold": 10, "direction": "exit" } ] }
Mandatory body parameters
sensorId
description: Sensors for which alert rule is to be created.
type: string.
example: Amcrest_1
rules
description: array of alert rules.
type: array.
example:
{ "rules": [ { "rule_id": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "id": "Amcrest_1", "type": "fov", "rule_type": "increment", "time_interval": 1, "count_threshold": 1, "direction": "entry" }, { "rule_id": "9c5632af-ba68-46bc-a997-858bdadc6856", "id": "Amcrest_1", "type": "fov", "rule_type": "increment", "time_interval": 5, "count_threshold": 10, "direction": "exit" } ] }
Each alert rule consists of following parameters:
Mandatory rule parameters
rule_id
description: Unique ID for this alert rule. This should be unique across all alert rules
type: string
example: UUID e.g fb298ea4-30aa-4085-b860-42e37c5bf8d1
id
description: Refers to the FOV for which alert rule applies. Since FOV are not required to be explicitly configured. This can contain the name of the sensor itself for FOV alert rule.
type: string
example: Amcrest_1
type
description: Type of analytics module. Fixed value ‘fov’
type: string
value: fov
rule_type
description: Type of alert rule. Fixed value ‘increment’
type: string
value: increment
time_interval
description: Time window. Specified in seconds.
type: float
example: 5
count_threshold
description: Threshold on number of people to consider for alert rule.
type: int
example: 10
direction
description: Directionality for the alert rule. Does it rule refer to number of objects leaving FOV (exit) or entering FOV (entry)
type: string
enum: One of entry/exit
example: exit
Optional rule parameters
- name
description: User friendly name for the alert rule. For display purpose on the client side
type: string
example: “Over crowding scenario rule”
Note
You will need to set User-Type=Admin in the HTTP header of the HTTP POST request.
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 500: Internal server error
Delete FOV alert rule
HTTP DELETE
/api/config/rule/alerts/fov?sensorId=Amcrest_1&ruleId=fb298ea4-30aa-4085-b860-42e37c5bf8d1
Mandatory query parameters
sensorId
description: Sensor for which FOV alert is to be deleted.
type: string
example: Amcrest_1
ruleId
description: Unique rule_id of the Alert rule which is to be deleted
type: string
example: fb298ea4-30aa-4085-b860-42e37c5bf8d1
Note: (Will need User-Type: Admin to be set in the HTTP header of the HTTP DEL request.)
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 422: No alert rule present for the specified sensor and rule Id 500: Internal server error
Retrieve FOV alert rule
HTTP GET
/api/config/rule/alerts/fov?sensorId=Amcrest_1
sensorId
description: Sensor for which fov alert rule needs to be returned.
type: string
example: sensorId=Amcrest_1
Error Response
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No alert rules present for the specified sensor 500: Internal server error
Retrieve all historical FOV alert rules
/api/config/rule/alerts/fov/history?sensorId=Amcrest_1
Mandatory query parameters
sensorId
description: Sensor for which historical fov alert rule needs to be returned.
type: string
example: sensorId=Amcrest_1
Error Response
Response body: See Error response body definition at the end of the page
HTTP Status codes:
422: No alert rules present for the specified sensor 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"
}