You can access the data that has been collected by Analytics DS via a REST API that is browsable. You can explore the API from the HTTP endpoint /api of the Analytics DS server. Parts of this REST-API are documented here.

Authentication

Each request to the API requires authentication. For this purpose, you can either use Basic Authentication or the authentication via a token.

Basic Authentication

You can use Basic Authentication as defined in RFC 7617 using the credentials of Analytics DS.

Token Authentication

Token authentication is an alternative to authentication based on a username and password. A token can be created from the administration area that you can access via /admin on the Analytics DS server. Each token belongs to a user and deleting it allows you to revoke it as a means for authentication. If you want to authenticate a request that way, add the following header:

Authorization

Token <token-key>

Example:
Authorization


Token f260fd489d127746df63669e8576eea8f22d89a6

Send Counting Event

In order to send a counting event to Analytics DS, you need to make a POST request to the endpoint /api/counting_event. The request body must contain either the MAC address (without colons) of a registered sensor and/or one or more IDs of counting groups as well as the actual counting value. The timestamp will be assigned by the Analytics DS server if no timestamp is provided. In case you want to send past events, you can either add a timestamp of the format YYYY-MM-DDTHH:mm:ss.SSSZ (e.g. 2020-06-12T10:11:48.819791Z) as the element "timestamp" or add the value "time_offset" in milliseconds (usually negative) to avoid the need for time synchronization between sensor and server.

Examples

Create a counting event for the device with 00:02:01:41:AB:1F with 4 incoming and 2 outgoing persons that is 35.4 seconds in the past. The counting event will be assigned to all counting groups that the device is assigned to.

{
    "mac_address": "00020141AB1F",
    "time_offset": -35400,
    "incoming": 4,
    "outgoing": 2
}
JSON

Create a counting event for the counting groups with IDs 1 and 3.

# Create a counting event for the groups with IDs 1 and 3
{
    "counting_groups": [1, 3],
    "incoming": 6,
    "outgoing": 0
}
JSON

Get Counter Values

You can get the current counter values by making a GET request to the endpoint /api/counting_group/<id>from which you receive the latest counter value as well as additional information of the counting group.

Example

{
    "id": 1,
    "name": "Store Berlin",
    "devices": [
        1
    ],
    "counter": 10,
    "created_date": "2020-05-13T14:15:40.714772Z",
    "updated_date": "2020-07-21T16:53:41.791654Z",
    "daily_reset": true,
    "daily_reset_time": "00:00:00",
    "weekly_reset": false,
    "weekly_reset_day": 6,
    "weekly_reset_time": "00:00:00",
    "visitor_maximum": 350,
    "timezone": "Europe/Berlin"
}
JSON

Query Counting Events

You can make queries to receive the history of counting events in an aggregated fashion via the endpoint /api/counting_group/<id>/data using HTTP GET requests and the following URL parameters:

Name

Description

from

POSIX timestamp (in seconds), UTC. Aggregate events starting from this timestamp.

to

POSIX timestamp (in seconds), UTC. Aggregate events until this timestamp.

aggregation_window

One of 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', defaults to 'day'. The window to aggregate counting events, e.g. 'day' will return daily results. Only the windows 'hour', 'minute', 'second' will return counter values.

An array of tuples of the following values will be returned:

  • timestamp (POSIX timestamp in seconds)

  • the sum of incoming visitors

  • the sum of outgoing visitors

  • counter value at the end of the aggregation window*

  • maximum counter value*

  • minimum counter value*

  • average counter value*
    * only available for aggregation windows that are less than a day ('hour', 'minute', 'second')

Get Sensor Information

You can get sensor information via the endpoint /api/device. For example, you will get the following list of sensors:

[
    {
        "id": 2,
        "name": "Sensor Entrance",
        "active": true,
        "mac_address": "801F12741F1E",
        "created_date": "2020-06-12T10:11:48.819791Z",
        "updated_date": "2020-07-20T12:51:24.553440Z"
    },
    {
        "id": 1,
        "name": "Sensor Exit",
        "active": true,
        "mac_address": "00020140A809",
        "created_date": "2020-05-13T14:15:36.186575Z",
        "updated_date": "2020-07-20T12:51:32.689779Z"
    }
]
JSON

Python Script for writing Counting Data as CSV

In the following, you can find an exemplary Python script that fetches the current counter value as well as the current number of visitors from the REST API and writes this data into a file called count.csv.

import datetime
import http.client
import base64
import json

host = '127.0.0.1'
username = 'your-username'
password = 'your-secret-password'
counting_group_id = 1

auth = base64.b64encode(f'{username}:{password}'.encode('utf-8')).decode('utf-8')

conn = http.client.HTTPConnection(host)
payload = ''
headers = {
    'Authorization': f'Basic {auth}'
}
conn.request('GET', f'/api/counting_group/{counting_group_id}/', payload, headers)
res = conn.getresponse()
data_counter = json.loads(res.read())

from_timestamp = int(datetime.datetime.now().replace(hour=0, minute=0, second=0).timestamp())
to_timestamp = int(datetime.datetime.now().timestamp())
conn.request('GET', f'/api/counting_group/{counting_group_id}/data/?from={from_timestamp}&to={to_timestamp}&aggregation_window=day', payload, headers)
res = conn.getresponse()
data_today = json.loads(res.read())
visitors_today = 0
if len(data_today) > 0:
    visitors_today = data_today[0][1]

with open('count.csv', 'w') as f:
    f.write('id,name,visitor_maximum,counter,visitors_today\n')
    f.write(f'{data_counter.get("id", "")},{data_counter.get("name", "")},{data_counter.get("visitor_maximum", 0)},{data_counter.get("counter", 0)},{visitors_today}')
PY