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 API Version v2

The FOV 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.

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/v2/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

bucketSizeInSec

description : Requested time range (fromTimestamp - toTimestamp) fragmented into histogram of interval bucketSizeInSec seconds. Minimum value of 1sec. Maximum value of 864000 sec (1 day)

type: int

objectType

description: An optional objectType 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. objectType=People,Vehicle

2) To return counts for all object types in addition to cumulative counts across all types of objects. objectType=*

3. When objectType is not specified it returns only cumulative counts across all types of objects.

Response

{

   "bucketSizeInSec": "1",
   "histogram": [
      {
      "end": "2020-01-26T19:16:30.000Z",
      "start": "2020-01-26T19:16:29.000Z",
      "objects": [
            {
               "type": "Person",
               "avgCount": 1,
               "minCount": 0,
               "maxCount": 2
            },
            {
               "type": "Vehicle",
               "avgCount": 1,
               "minCount": 1,
               "maxCount": 4
            }
         ]
      },
      {
      "end": "2020-01-26T19:16:29.000Z",
      "start": "2020-01-26T19:16:28.000Z",
      "objects": [
            {
               "type": "Person",
               "avgCount": 1,
               "minCount": 0,
               "maxCount": 2
            },
            {
               "type": "Vehicle",
               "avgCount": 1,
               "minCount": 1,
               "maxCount": 4
            }
         ]
      }
   ]
}

Response body attributes

histogram

description: Histogram of counts for each type of objects (e.g People, Vehicle,…)

type: Array of object

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/v2/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/v2/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

objectType

description: An optional objectType 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. objectType=People,Vehicle

2) To return counts for all object types in addition to cumulative counts across all types of objects. objectType=*

3. When objectType is not specified it returns only cumulative counts across all types of objects.

Response

{
    "fovOccupancy": [
      {
        "sumCount": 10
        "averageCount": 2
        "type": "People"
      },
      {
        "sumCount": 20
        "averageCount": 3
        "type": "Vehicle"
      }
   ]
}

Response body attributes

fovOccupancy: An array of count items. Where each item contains the counts for a specific type of object (“People”,”Vehicle”)

Following are the attributes for each item

sumCount

description: Total unique count for a type of object (e.g People, Vehicle,…)

type: integer

averageCount

description: Average count for a type of object (e.g People, Vehicle,…)

type: integer

type

description: Object type (e.g People, Vehicle,…)

type: string.

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/v2/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/v2/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/v2/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",
               "ruleType": "increment",
               "sensorId": "Amcrest_3",
               "startTimestamp": "2021-09-16T06:06:59.800Z",
               "type": "fov",
               "direction": "entry",
               "attributes": [
                  {
                     "name": "objects",
                     "value": [
                        {
                              "id": "1186",
                              "type": "People"
                        }
                     ]
                  }
               ]
         },
         {
               "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",
               "ruleType": "occupancy",
               "sensorId": "Amcrest_3",
               "startTimestamp": "2021-09-16T06:06:59.800Z",
               "type": "fov",
               "attributes": [
                  {
                     "name": "objects",
                     "value": [
                        {
                              "id": "1186",
                              "type": "People"
                        }
                     ]
                  }
               ]
         },
         {
               "count": 5,
               "description": "FOV occupancy count greater than 5",
               "duration": 10.734,
               "endTimestamp": "2021-09-16T06:07:00.534Z",
               "id": "unique-alert-id",
               "ruleType": "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=People.

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/v2/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 countThreshold of people present in the FOV continuously for longer than timeInterval 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/v2/config/rule/alerts/fov

{
   "sensorId": "Amcrest_1",
   "rules": [
      {
         "ruleId": "d8f0484f-b464-4a92-a5a9-649a14160b53",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "occupancy",
         "name": "Overcrowding scenario rule",
         "timeInterval": 10,
         "countThreshold": 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:

{
   "ruleId": "cd2218f6-e4d2-4ad4-9b15-3396e4336064",
   "id": "Amcrest_1",
   "name": "Over crowding scenario rule",
   "type": "fov",
   "ruleType": "occupancy",
   "timeInterval": 10,
   "countThreshold": 100
}

Each alert rule consists of following parameters:

Mandatory rule parameters

ruleId

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

ruleType

description: Type of alert rule. Fixed value ‘occupancy’

type: string

value: occupancy

timeInterval

description: Time window. Specified in seconds.

type: float

example: 10

countThreshold

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 countThreshold 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/v2/config/rule/alerts/fov

{
   "sensorId": "Amcrest_1",
   "rules": [
      {
         "ruleId": "ae511b25-a57d-483f-b4c5-c30e039cc375",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "occupancy_threshold_switch",
         "timeInterval": 1,
         "countThreshold": 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:

{
   "ruleId": "ae511b25-a57d-483f-b4c5-c30e039cc375",
   "id": "Amcrest_1",
   "type": "fov",
   "ruleType": "occupancy_threshold_switch",
   "timeInterval": 1,
   "countThreshold": 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

ruleId

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

ruleType

description: Type of alert rule. Fixed value ‘occupancy_threshold_switch’

type: string

value: occupancy_threshold_switch

timeInterval

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

countThreshold

description:

Number of counts threshold used to determine status

1. countThreshold 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.

2. positive non-zero countThreshold (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 countThreshold of object entered/exited in the field of view within timeInterval seconds.

Create a new alert rule

HTTP POST

/api/v2/config/rule/alerts/fov

{
   "sensorId": "Amcrest_1",
   "rules": [
      {
         "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 1,
         "countThreshold": 1,
         "direction": "entry"
      },
      {
         "ruleId": "9c5632af-ba68-46bc-a997-858bdadc6856",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 5,
         "countThreshold": 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": [
      {
         "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 1,
         "countThreshold": 1,
         "direction": "entry"
      },
      {
         "ruleId": "9c5632af-ba68-46bc-a997-858bdadc6856",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 5,
         "countThreshold": 10,
         "direction": "exit"
      }
   ]
}

Each alert rule consists of following parameters:

Mandatory rule parameters

ruleId

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

ruleType

description: Type of alert rule. Fixed value ‘increment’

type: string

value: increment

timeInterval

description: Time window. Specified in seconds.

type: float

example: 5

countThreshold

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/v2/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 ruleId 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/v2/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/v2/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.

{
   "error": "#Detailed error string",
}