Build interactive reports with Unleash live API Analytics

4 min readOct 28, 2020

Our customers love the freedom of connecting any camera type and v. Another aspect customers love is the freedom to integrate the data into their workflow.

Today we are adding to our existing portfolio of output options such as live Esri dashboard, SMS, Slack and MS Teams notification with our powerful Analytics API.

In this article, we’re excited to share our recently released version.

The Analytics API exposes read-only endpoints to authorized users, allowing customers to automatically retrieve Unleash live A.I. generated analytics data and custom integrations with the Unleash live ecosystem.

This is a technical article providing a simple user case to get you started. If you would like to learn more about how the Analytics API can be integrated into your business workflow, get in touch, we’d love to show you.

Back to the technical. This article is also available as a notebook here if you would prefer to test the API in real time!

The Basics

To start with, our analytics API documentation can be found at developer.unleashlive.com.

Code examples are provided in both BASH (using curl) and in Python 3 with the urllib3 library, which comes standard with most web environments (such as google compute and AWS Lambda).

Authentication is performed by providing an ‘x-api-key’ header with your request.

You’ll also need an API key to get started — for this example we can use a test key:

s9DgN7EXDw3hST32dquq44GICMeINPBxASgC3OKb

To test your setup is working correctly, you can perform a quick version check with curl:

curl -X GET -H “x-api-key: <API-KEY>” https://api.unleashlive.com/v1/analytics/version

Which should return a version number if successful:

“0.0.1”

Devices

You can find a list of all of your devices within your Unleash live account under “Device Management” — if you don’t have an account yet, you can sign up for a free trial here, but for this article we’ll be using some pre-configured test devices.

You can find your device ID by hitting the “manage” button

You can also query the API for a list of available devices using the /analytics/devices endpoint, which will return a list of devices. For the test API key, this endpoint should return the following:

[‘Wb109bb2283c0129’, ‘W9e2acb15068fc53’, ‘T9x8e76wtrc88n8m’, ‘Tjh6lkj37g85d763’]

Of which ‘T9x8e76wtrc88n8m’ and ‘Tjh6lkj37g85d763’ contain data, between the 24th and 30th of August, 2020, Australian Eastern Standard Time (AEST), or 1598190900 and 1598795700 in Unix time.

While all devices with API access are returned, this is no guarantee that analytics data is available for each device, and so it is recommended that you ensure analytics are being generated in your account before attempting to access them with the Analytics API.

Sign up to our newsletter to stay up to date with the latest industry applications of Unleash live

Measuring Reality

With a working API key and the knowledge of which devices we want to analyze, we can put together our first real API request.

Data for a specific device and time period can be requested with the following endpoint:

GET/analytics/{deviceId}/{unixUTCTimeStampFrom}/{unixUTCTimeStampTo}/{pageNumber}

The main request is pretty self explanatory — deviceId is the device we found earlier, unixUTCTimeStampFrom and unixUTCTimeStampTo identify a period of time to return data from, and pageNumber, which should be 1 for the initial request.

For our data — deviceId T9x8e76wtrc88n8m, unix times from 1598190900 to 1598795700 and with page number 1, we get something like this:

Which is a lot of data. The Analytics API is currently on a per-detection basis, allowing customers to do their own aggregations or transforms on the data.

The returns, returns three items — “keys”, a list of keys for the main data list, “total_num_pages”, the total number of pages for the requested time period and “data”, which is a list of lists containing each A.I generated analytic data point.

Importantly, total_num_pages for this request is 4 — so we should do the request again, substituting pageNumber for 2, 3 and 4 to build up the rest of the data table.

Turning data into insights

Now that we have all of our data sitting in one convenient location, we can graph something.

Let’s start by finding out what data we have — using something like df[‘class_name’].unique() from Pandas, we find out that we have the following data points:

[‘this_frame_persons_count’, ‘num_individuals’, ‘group_pixel_size’,
‘number_of_persons_in_group’, ‘total_count’, ‘number_of_groups’]

This data comes from our Social Distancing model — total_count gives us the total number of people within each video.

Displaying this with a Pandas graph gives a graph like the following, showing the number of people during daylight hours in a public space:

This graph represents the number of people per day

We can already make out some easy trends — the middle of the day on August 29th and 30th were the busiest days by far, which makes sense as they occurred on a weekend.

Next time, we’ll look at combining data from multiple devices, and using the full capabilities of this particular AI App to measure social distancing.

The Unleash live Analytics API allows you to extract and work with A.I. generated data in the business tool or application of your choice.

Get Started with Unleash live

Visit unleashlive.com to start your free trial or book a time with one of our specialist team members to learn how your business can take advantage of live streaming video and A.I. analytics.