Technical Support | Suprema

This article will guide you through retrieving event logs from BioStar 2 server via BioStar 2 API.

You can find a more detailed introduction to BioStar 2 New Local API in this article : [BioStar 2 API] How To Use BioStar 2 New Local API

In this article, you can learn how to call an API function to retrieve the log data within a specific timeframe.

This article also includes a sample code of a C# program that incorporates the API, and also an example of API call made via Postman, a program used for building & testing RESTful API calls.

Part 1. API Call & Parameters

[POST]: /events/search

You can also find information regarding this API in the following link : Search Events API Documentation

[Parameters]

Parameter	Type	Required	Description
limit	Number	Y	Limit the response records by the value stated on this parameter
conditions	Array	N	Array of conditions
:column	String		Field which the conditions will be based from. ['datetime','device_id.id','door_id.id','event_type_id.code', 'user_group_id.id','user_id.user_id','server_datetime'] Required if you want to add conditions
:operator	Number		Condition Operator EQUAL : 0, NOT_EQUAL : 1, CONTAINS : 2, BETWEEN : 3, LIKE : 4, GREATER : 5, LESS : 6 For field encrypted in encryption mode (ex. user_id.user_id), it only supports Equal (0), Not Equal (1), and Contains(2). Required if you want to add conditions
:values	String Array		Value for the conditions. (If condition is for 'datetime', datetime needs to be in UTC ISO-8601 format. ex: 2015-06-10T02:14:05.268Z ) Required if you want to add conditions
orders		N	sort logs.
:column	String		Field which the sorting will be based on Required if you want to add orders
:descending	Boolean		Toggle true to set the sorting as descending Required if you want to add orders

Part 2. Request Body & Response Model

[Request Body Example]

{

"Query": {

"limit": 100,

"conditions": [

{

"column": "datetime",

"operator": 3,

"values": [

"2021-08-01T15:00:00.000Z",

"2021-08-02T14:59:59.000Z"

]

}

]

}

* "limit" : 100 indicates that you’d only see 100 logs in the response as a result of the API call.

* Please set this value accordingly since retrieving a large amount of data can cause delays or server crashes. (Recommended Max. limit: 2,000)

* "conditions" : in the example above, it's filtering the logs by 'datetime (column : datetime)' by retrieving the logs that occurred 'between (operator - 3)' 2021-08-01T15:00:00.000Z and 2021-08-02T14:59:59.000Z (from "values").

So in this case, you’ll only see the logs from 2021-08-01T15:00:00.000Z to 2021-08-02T14:59:59.000Z.

* If you change the "column" to "id" or other values, it will filter the logs by their id or other values accordingly.

NOTE : If you want to filter by "server_datetime", you need to put ' before and after the dates in the "values" field. 

For Example,
 {
     "Query" : {
         "limit" : 20,
         "conditions" : [
          {
               "column" : "server_datetime", 
               "operator" : 3, 
               "values" : [
                     "'2024-09-22T15:00:00.000Z'",
                     "'2024-09-23T15:00:00.000Z'"
               ]
         }
     }
 }

[Response: Successful]

{

"EventCollection": {

"rows": [

{

"id": "133",

"server_datetime": "2021-08-02T13:08:27.00Z",

"datetime": "2021-08-02T04:08:30.00Z",

"index": "346",

"user_group_id": {

"id": "0",

"name": ""

"device_id": {

"id": "939271697",

"name": "BioStation A2 939271697 (192.168.13.132)"

"event_type_id": {

"code": "20736"

"door_id": [

{

"id": "4",

"name": "Door1"

}

"is_dst": "0",

"timezone": {

"half": "0",

"hour": "9",

"negative": "0"

"user_update_by_device": "false",

"hint": "162787731009392716970000000346",

"user_id": {

"photo_exists": "false"

}

"server_datetime" refers to the timestamp when the logs from the device get synchronized to the server. "datetime" refers to the timestamp when the event actually occurs on the device.

"timezone" holds information regarding the timezone set in the device of which the log occurred.

To find more information regarding these values, please refer to the following article :

[BioStar 2 API] How to Interpret Time in Device Timezone from Event Log API

Part 3. Console Retrieve Logs Example

This is a sample of Visual C# console application made for those who might need some guide for integrating the BioStar 2 New Local API.

You can simply copy & paste the source code to use the same function in your own integration.

[Retrieve Logs Method Source Code]

static async void GetLogTask()

{

if(sessionID == null)

{

Console.WriteLine("You must log in first!");

return;

}

CookieContainer cookieContainer = new CookieContainer();

HttpClientHandler handler = new HttpClientHandler();

handler.CookieContainer = cookieContainer;

HttpClient httpClient = new HttpClient(handler);

HttpClient client = new HttpClient(handler);

httpClient.DefaultRequestHeaders.Add("bs-session-id", sessionID);

cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID));

string resourceAddress = "https://127.0.0.1/api/events/search";

Console.WriteLine("How many results do you want to see?");

string limit = Console.ReadLine();

string startTime = "1970-01-01T00:00:00Z";

string endTime = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ");

DateTime dtLatestLogTime = new DateTime(1970, 1, 1);

JavaScriptSerializer serializer = new JavaScriptSerializer();

string payload2 = "{ \"Query\": { \"limit\": " + limit + ", \"conditions\": [ { \"column\": \"datetime\", \"operator\": 3, \"values\": [ \"" + startTime + "\", \"" + endTime + "\" ] } ] }}";

Console.WriteLine(payload2);

StringContent sc = new StringContent(payload2, Encoding.UTF8, "application/json");

HttpResponseMessage httpResponse = httpClient.PostAsync(resourceAddress, sc).Result;

if (httpResponse.IsSuccessStatusCode == true)

{

Console.WriteLine("Succeeded to retrieve log from " + startTime + " to " + endTime);

string httpResponseBody = await httpResponse.Content.ReadAsStringAsync();

//Console.WriteLine(httpResponseBody);

dynamic obj = JsonConvert.DeserializeObject(httpResponseBody);

Console.WriteLine("************** LOG("+limit+") : **************");

Console.WriteLine("** LogID ********* DateTime *********** DeviceID ******************** DeviceName ********************* EventCode *****");

for (int i = 0; i < Int16.Parse(limit); i++)

{

Console.WriteLine(obj.EventCollection.rows[i].id + " " + obj.EventCollection.rows[i].datetime + " " + obj.EventCollection.rows[i].device_id.id + " " + obj.EventCollection.rows[i].device_id.name + " " + obj.EventCollection.rows[i].event_type_id.code);

}

System.Threading.Thread.Sleep(1000);

}

else

{

Console.WriteLine("Log Retrieval Failed from " + startTime + " to " + endTime);

Console.WriteLine(httpResponse.ToString());

}

[After Retrieve Logs Successfully: only managed to see a few values of the logs]