Getting started with the Analytics API

The Bitmovin Analytics API lets us query for usage data of our videos. We can filter, aggregate and group data in the API request already, so we’re able to fetch precisely the data we need. In this section you’ll learn how to analyse the performance of your video platform and how to learn more about people watching your videos.

Installation

To get started, we need the Bitmovin API client. We’ll use the JavaScript client in all examples, but there are clients for several other languages as well. If you haven’t already, install the Bitmovin client:

npm install @bitmovin/api-sdk

Preparing the query builder

Let’s create an analytics query builder in your Javascript application:

import Bitmovin from 'bitmovin-javascript';  
const bitmovin = new Bitmovin({ apiKey: '<YOUR API KEY>' });  
const queryBuilder = bitmovin.analytics.queries.builder;  
const fromDate = new Date();  
fromDate.setDate(1);  
const toDate = new Date();  
toDate.setDate(7);

Here we use the first week of the current month, but feel free to specify your own fromDate and toDate. Please just keep in mind that your data is only retained for a certain amount of time. For standard retention time is 30 days.

Your first Query

The query builder provides us with a nice query interface.
The minimal set of instructions to build the query are:

• .sum('PLAYED') - some kind of metric - it is described by the combination of aggregation method and dimension
  • aggregation methods: count, avg, sum, max, min
  • dimension: PLAY_ATTEMTS, PLAYED, BUFFERED, IMPRESSION and many more
• .between(startDate, endDate) - a timeframe - it is always defined by a start date and an end date. The query will consider data collected between those two dates.

After you’ve composed your query, you call the .query() method which submits the API request and returns a Promise. This promise resolves when the API request finishes. In this case we want to log the result to the console, so we pass console.log as callback function to the then() method of the promise.

Let’s try running a query for the total view time:

queryBuilder  
  .sum('PLAYED')
  .between(fromDate, toDate)  
  .query()  
  .then(console.log);

If everything worked out, the total view time in the given interval is printed to your console.

Refine your query

In order to properly analyse you video product you need to understand what is going on there. There are many options you can use to further enhance your query by only selecting a subset of the data or change the layout of the data.
Here are a few options:

• .orderBy('FUNCTION', 'ASC') - order your data set using the current metric or other dimension
  • your can also use DESC for descending ordering
• .groupBy('PLATFORM') - separate your data based on the select category.
• .filter('PLATFORM', 'EQ', 'web') - filter out a subset of you data.
• .interval('HOUR') - aggregate the data based on the interval it happened. (HOUR, DAY, MINUTE)

Get inspired

Checkout How to recreate dashboard queries via the api to see which queries we use in our dashboard

But here are some other inspirations

Sessions which had an error by platforms

queryBuilder  
  .count('IMPRESSION')
  .between(fromDate, toDate)
	.filter('ERROR_CODE', 'NE', null)
	.groupBy('PLATFORM')
  .query()  

How many users are watching that video?

queryBuilder
  .count('IMPRESSION_ID')
  .between(fromDate, toDate)
  .interval('MINUTE')
  .filter('VIDEO_ID', 'EQ', 'my-livestream-id')
  .query()