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 Jetons device IP. Replace the INGRESS-PORT with 30080 or the last value defined in Ingress configuration.
Create tripwire configuration
HTTP POST
/api/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/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
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 return 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.tripwire.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.tripwire.barCount.min+metrics.tripwire.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.
Example
HTTP GET
/api/metrics/tripwire/histogram?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z&fixedInterval=1000
The 5 minutes time range is fragmented into histograms of 1sec (1000 msec) fixed interval.
Response
{ "alerts": [], "counts": [ { "agg_window": "2 sec", "histogram": [ { "end": "2020-01-26T19:16:30.000Z", "start": "2020-01-26T19:16:29.000Z", "sum_count": 0 }, { "end": "2020-01-26T19:17:29.000Z", "start": "2020-01-26T19:17:28.000Z", "sum_count": 1.0 } ], "attributes": [ { "name": "tripwireId", "value": "door1" }, { "name": "tripwireName", "value": "Main Door" }, { "name": "directionName", "value": "Inside the room" }, { "name": "direction", "value": "entry" } ], "sensorId": "Amcrest_3", "type": "exit" }, { "agg_window": "2 sec", "histogram": [ { "end": "2020-01-26T19:16:30.000Z", "start": "2020-01-26T19:16:29.000Z", "sum_count": 0 }, { "end": "2020-01-26T19:17:29.000Z", "start": "2020-01-26T19:17:28.000Z", "sum_count": 1.0 } ], "attributes": [ { "name": "tripwireId", "value": "door1" }, { "name": "tripwireName", "value": "Main Door" }, { "name": "directionName", "value": "Inside the room" }, { "name": "direction", "value": "entry" } ], "sensorId": "Amcrest_3", "type": "entry" } ], "object_type_counts":{ "Person":[ { "agg_window": "2 sec", "histogram": [], "attributes": [], "sensorId": "Amcrest_3", "type": "exit" }, { "agg_window": "2 sec", "histogram": [], "attributes": [], "sensorId": "Amcrest_3", "type": "entry" } ], "Vehicle":[ { "agg_window": "2 sec", "histogram": [], "attributes": [], "sensorId": "Amcrest_3", "type": "exit" }, { "agg_window": "2 sec", "histogram": [], "attributes": [], "sensorId": "Amcrest_3", "type": "entry" } ] } }
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 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/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
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.
Example
HTTP GET
/api/metrics/tripwire/count?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z
Response
{ "counts": [ { "total_count": 5 "sensorId": "Amcrest_3", "count_by_type": { "Person": 3, "Vehicle": 2 }, "attributes": [ { "name": "tripwireId", "value": "door1" }, { "name": "tripwireName", "value": "Main Door" }, { "name": "directionName", "value": "Inside the room" }, { "name": "direction", "value": "entry" } ], }, { "total_count": 10, "count_by_type": { "Person": 7, "Vehicle": 3 }, "attributes": [ { "name": "tripwireId", "value": "door1" }, { "name": "tripwireName", "value": "Main Door" }, { "name": "directionName", "value": "Outside the room" }, { "name": "direction", "value": "exit" } ], "sensorId": "Amcrest_3" } ] }
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 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 count_threshold crossing the tripwire line within time_interval seconds.
HTTP POST
/api/config/rule/alerts/tripwire
{ "sensorId": "Amcrest_1", "rules": [ { "rule_id": "cd2218f6-e4d2-4ad4-9b15-3396e4336064", "id": "MAIN", "type": "tripwire", "rule_type": "flowrate", "time_interval": 1, "count_threshold": 10, "direction": "entry" }, { "rule_id": "6f12fd2e-42eb-41aa-b221-44c1368b747f", "id": "MAIN", "type": "tripwire", "rule_type": "flowrate", "time_interval": 1, "count_threshold": 2, "direction": "exit" } ] }
Mandatory query 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: 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
time_interval
description: Time window. Specified in seconds.
type: integer
example: time_interval: 10
count_threshold
description: Number of crossings.
type: integer
example: count_threshold: 10
rule_type
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 count_threshold of object entry/exit crossing the tripwire line within time_interval seconds.
HTTP POST
/api/config/rule/alerts/tripwire
{ "sensorId": "Amcrest_1", "rules": [ { "rule_id": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "id": "MAIN", "type": "tripwire", "rule_type": "increment", "time_interval": 5, "count_threshold": 15, "direction": "entry" }, { "rule_id": "9c5632af-ba68-46bc-a997-858bdadc6856", "id": "MAIN", "type": "tripwire", "rule_type": "increment", "time_interval": 5, "count_threshold": 10, "direction": "exit" } ] }
Mandatory query 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: 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
rule_type
description: Type of alert rule. Fixed value ‘increment’
type: string
value: increment
time_interval
description: Time window. Specified in seconds.
type: integer
example: time_interval: 10
count_threshold
description: Number of alert counts.
type: integer
example: count_threshold: 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/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 rule_id 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/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", "rule_type": "increment", "rule_id": "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", "rule_id": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "rule_type": "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/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/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",
"status": "#http-status-code",
"title": "Unprocessable Entity",
"type": "about:blank"
}