Tripwire API Guide#
Overview#
Tripwire is a functional module in the Metropolis Analytics microservice that detects object crossing a defined tripwire line and provides time series metrics, and alerts related to it.
Tripwire 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.
Tripwire API Version v2#
The Tripwire 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.
Create tripwire configuration#
HTTP POST
/api/v2/config/tripwire?sensorId=Amcrest_3
{ "deleteIfPresent": true, "tripwires": [ { "direction": { "entry": { "name": "Inside the room" }, "exit": { "name": "Outside of the room" }, "p1": { "x": 753, "y": 744 }, "p2": { "x": 448, "y": 856 } }, "id": "door1", "name": "Main door", "wire": [ { "x": 321, "y": 664 }, { "x": 544, "y": 648 }, { "x": 656, "y": 953 }, { "x": 323, "y": 1067 } ] } ], "sensorId": "Amcrest_3" }
Mandatory query parameters#
sensorId
description: Sensor for which Tripwire config needs to be inserted.
type: string
example: sensorId=Amcrest_3
direction.p1
description: the (x,y) coordinate of the tail of the direction arrow.
type: Dict{x: int, y: int}
example: direction.p1={“x”: 323, “y”: 1067}
direction.p2
description: the (x,y) coordinate of the head of the direction arrow.
type: Dict{x: int, y: int}
example: direction.p1={“x”: 448, “y”: 858}
Optional query parameters#
direction.entry.name
description: User friendly name of the direction of crossing towards the entry side of tripwire
type: string
example: Inside the room
direction.exit.name
description: User friendly name of the direction of crossing towards the exit side of tripwire
type: string
example: Outside of the room
deleteIfPresent
description: If true any existing tripwire timeseries data will be delete for this tripwire.
type: boolean
If not specified or false the tripwire timeseries data is retained.
Note: 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
Retrieve Tripwire histogram counts#
Histogram of count people crossing the tripwire lines for a given time range and a specified fixed interval.
HTTP GET
/api/v2/metrics/tripwire/histogram?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z
Mandatory query parameters#
sensorId
description: Sensor for which Tripwire metrics need to be returned.
type: string
example: sensorId=Amcrest_3
tripwireId
description: tripwire line for which Tripwire metrics need to be returned.
type: string
example: door1
fromTimestamp
description: lower bound of the timestamp for which tripwire 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 tripwire 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 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. objectType=People,Vehicle
2) To return counts for all object types in addition to cumulative counts across all types of objects. objectType=*
When objectType is not specified it returns only cumulative counts across all types of objects.
Example#
HTTP GET
/api/v2/metrics/tripwire/histogram?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z&bucketSizeInSec=1
The 5 minutes time range is fragmented into histograms of 1sec fixed interval.
Response#
{ "bucketSizeInSec": "1", "tripwires": [ { "id": "door_1", "histogram": [ { "end": "2020-01-26T19:16:30.000Z", "start": "2020-01-26T19:16:29.000Z", "events": [ { "type": "IN", "objects": [ { "type": "Person", "count": 1 }, { "type": "Box", "count": 4 } ] }, { "type": "OUT", "objects": [ { "type": "Person", "count": 2 }, { "type": "Box", "count": 1 } ] } ] } ] } ] }
Response body attributes#
tripwires[].histogram
description: Histogram of count for all types of objects (e.g People, Vehicle,…) per tripwire and direction type (IN/OUT)
type: Array of object
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No Tripwire metrics found for the requested sensorId and time range 500: Internal server error
Retrieve Tripwire total counts#
Total count of people crossing the tripwire lines for a given time range
HTTP GET
/api/v2/metrics/tripwire/count?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z
Mandatory query parameters#
sensorId
description: Sensor for which Tripwire metrics need to be returned.
type: string
example: sensorId=Amcrest_3
tripwireId
description: tripwire line for which Tripwire metrics need to be returned.
type: string
example: door1
fromTimestamp
description: lower bound of the timestamp for which tripwire 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 tripwire 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 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. objectType=People,Vehicle
2) To return counts for all object types in addition to cumulative counts across all types of objects. objectType=*
When objectType is not specified it returns only cumulative counts across all types of objects.
Example#
HTTP GET
/api/v2/metrics/tripwire/count?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z
Response#
{ "tripwireKpis": [ { "id": "door1", "events": [ { "type": "IN", "objects": [ { "type": "People", "count": 2 } ] }, { "type": "OUT", "objects": [ { "type": "People", "count": 1 } ] } ] } ] }
Response body attributes#
tripwireKpis[].id
description: Id of the tripwire for which the counts provided in events.
type: string
tripwireKpis[].events[].type
description: Direction of crossing e.g IN/OUT
type: string
tripwireKpis[].events[].objects[]
description: Count specific to a type of object
type: object
tripwireKpis[].events[].objects[].type
description: Type of the object
type: string
tripwireKpis[].events[].objects[].count
description: Count specific to a type of object
type: integer
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No Tripwire metrics found for the requested sensorId and time range 500: Internal server error
Create Tripwire alert rule#
Two types of alerts rule i.e. Increment and Flow Rate are supported
Flow Rate Alert Type#
Alerts based on every countThreshold crossing the tripwire line within timeInterval seconds.
HTTP POST
/api/v2/config/rule/alerts/tripwire
{ "sensorId": "Amcrest_1", "rules": [ { "ruleId": "cd2218f6-e4d2-4ad4-9b15-3396e4336064", "id": "MAIN", "type": "tripwire", "ruleType": "flowrate", "timeInterval": 1, "countThreshold": 10, "direction": "entry" }, { "ruleId": "6f12fd2e-42eb-41aa-b221-44c1368b747f", "id": "MAIN", "type": "tripwire", "ruleType": "flowrate", "timeInterval": 1, "countThreshold": 2, "direction": "exit" } ] }
Mandatory query 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: tripwire line for which Tripwire alert rule is being specified.
type: string
example: id: MAIN
type
description: Type of analytics module this alert relates to. Fixed value ‘tripwire’
type: string
example: tripwire
timeInterval
description: Time window. Specified in seconds.
type: integer
example: timeInterval: 10
countThreshold
description: Number of crossings.
type: integer
example: countThreshold: 10
ruleType
description: Type of alert rule. Fixed value ‘flowrate’
type: string
value: flowrate
direction
description: Directionality for the alert rule. Does it rule refer to objects crossing in the direction of entry (entry) or on the opposite direction (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: 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 Type#
Alerts based on countThreshold of object entry/exit crossing the tripwire line within timeInterval seconds.
HTTP POST
/api/v2/config/rule/alerts/tripwire
{ "sensorId": "Amcrest_1", "rules": [ { "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "id": "MAIN", "type": "tripwire", "ruleType": "increment", "timeInterval": 5, "countThreshold": 15, "direction": "entry" }, { "ruleId": "9c5632af-ba68-46bc-a997-858bdadc6856", "id": "MAIN", "type": "tripwire", "ruleType": "increment", "timeInterval": 5, "countThreshold": 10, "direction": "exit" } ] }
Mandatory query 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: Tripwire Id for which alert rule is being specified.
type: string
example: id: MAIN
type
description: Type of analytics module. Fixed value ‘tripwire’
type: string
value: tripwire
ruleType
description: Type of alert rule. Fixed value ‘increment’
type: string
value: increment
timeInterval
description: Time window. Specified in seconds.
type: integer
example: timeInterval: 10
countThreshold
description: Number of alert counts.
type: integer
example: countThreshold: 10
direction
description: Directionality for the alert rule. Does it rule refer to objects crossing in the direction of entry (entry) or on the opposite direction (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 Tripwire alert rule#
HTTP DELETE
/api/v2/config/rule/alerts/tripwire?sensorId=Amcrest_1&tripwireId=MAIN&ruleId=fb298ea4-30aa-4085-b860-42e37c5bf8d1
Mandatory query parameters#
sensorId
description: Sensor for which Tripwire alert needs to be deleted.
type: string
example: sensorId=Amcrest_11
tripwireId
description: id of the tripwire for which this alert rule is to be deleted
type: string
example: id=MAIN
ruleId
description: Unique ruleId of the Alert rule which is to be deleted
type: string
example: fb298ea4-30aa-4085-b860-42e37c5bf8d1
Note: You will need to set User-Type: Admin 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 sensorId, tripwireId and ruleId 500: Internal server error
Retrieve Tripwire alerts#
Alerts can be retrieved using the family of APIs which has filtering for sensor, Tripwire Line, timeranges with optional support for pagination.
All Tripwire Alerts for a specific sensor for time range#
HTTP GET
/api/v2/alerts/tripwire?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
Response:#
{ "alerts": [ { "count": 10, "description": "10 people exited tripwire", "duration": 0.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "ruleType": "increment", "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "sensorId": "Amcrest_1", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "tripwire", "direction": "entry", "directionName": "Inside the room", "attributes": [ { "name": "tripwireId", "value": "door1" }, { "name": "tripwireName", "value": "Main Door" }, { "name": "directionName", "value": "Inside the room" }, { "name": "direction", "value": "entry" }, { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ], }, { "count": 2, "description": "flowrate exceeds 2 ppl/s in 5 second window", "duration": 0.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "ruleType": "flowrate", "sensorId": "Amcrest_1", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "tripwire", "direction": "exit", "directionName": "Out of the room", "attributes": [ { "name": "tripwireId", "value": "door1" }, { "name": "tripwireName", "value": "Main Door" }, { "name": "directionName", "value": "Out of the room" }, { "name": "direction", "value": "exit" } ], } ] }
Mandatory query parameters#
sensorId
description: Sensor for which Tripwire alerts need to be returned.
type: string
example: sensorId=Amcrest_11
fromTimestamp
description: lower bound of the timestamp for which tripwire alert needs to be returned
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which tripwire 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#
limit
description: Max number of alerts to be returned
type: integer
It follows Time based simple pagination. Get 10 (limit) alerts which occurred b/w 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (endTimestamp). Criteria is that endTimestamp > fromTimestamp
Response body attributes#
Alerts of type increment 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 Tripwire alerts found for the requested sensorId,tripwireId and time range 500: Internal server error
Example#
/api/v2/alerts/tripwire?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z&limit=10
Delete tripwires configuration#
HTTP DELETE
/api/v2/config/tripwire?sensorId=Amcrest_1&tripwireId=MAIN
Mandatory query parameters#
sensorId
description: Sensor for which Tripwire config needs to be deleted.
type: string
example: sensorId=Amcrest_11
tripwireId
description: tripwire line for which Tripwire config needs to be returned.
type: string
example: tripwireId=MAIN
Note
You will need to set User-Type: Admin in the HTTP header of the HTTP DELETE 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 Tripwire configuration found for the specified sensorId and tripwireId 500: Internal server error
Error Response body:#
Error response for all API is JSON object with following attributes.
{
"detail": "#Detailed error string"
}