Analytics

Normal

large_logo_avatar.webp

medium_logo_avatar.webp

small_logo_avatar.webp

thumbnail_logo_avatar.webp

logo_avatar.webp

api.video

large_api-video-blog-tutorials.png

medium_api-video-blog-tutorials.png

small_api-video-blog-tutorials.png

thumbnail_api-video-blog-tutorials.png

api-video-blog-tutorials.png

Tutorials

JavaScript

Understanding your audience is key to successful video and live stream content delivery. Whether you deliver your own content, or develop a mobile app which enables creatives to deliver their own, leveraging data and analytics can help you. With api.video's [Analytics solution](https://docs.api.video/analytics/overview), you gain vital insights into the viewers’ preferences and behaviors, enabling you or your users to make data-informed decisions in content creation, and engage better with the audience.

&nbsp;
 

**In this tutorial, we’ll go through two methods that you can use to retrieve analytics data for your videos and live streams.**

## What data?

The mainspring of api.video’s Analytics solution is **play event data**. Play events determine the number of times your video or live stream had viewer engagement. 
&nbsp;
 
api.video’s solution analyzes and groups play event data by these dimensions:

&nbsp;
 

- the date and time of the play event,
- the ID of a specific video or live stream that generated play events
- the countries where your viewers are based,
- the device type your viewers are using, like `phone` or `computer`
- the browser your viewers are using, like `Chrome` or `Firefox`
- the operating system that your users are running, like `iOS` or `Windows`
&nbsp;
 
api.video helps you read and filter this data, enabling you to segment and understand your audience better.

## Requirements

Before we discuss the two methods, let’s talk about some requirements. api.video can only generate analytics data when you meet these simple requirements:

&nbsp;

1. You have already uploaded videos or broadcasted live streams.
2. These videos or live streams already had viewers that create play events.
3. You used the api.video player to deliver your content. You will meet this requirement when you integrate one of [api.video’s Player SDKs](https://docs.api.video/sdks/player), or embed the video or the live stream into a website, or simply share the video or live stream URL with your viewers.


large_Blog_illustration_analytics.png

medium_Blog_illustration_analytics.png

small_Blog_illustration_analytics.png

thumbnail_Blog_illustration_analytics.png

Blog_illustration_analytics.png

You can also use a different player solution, however, you will need to integrate api.video’s [analytics plug-ins](https://docs.api.video/sdks/player#player-analytics-sdks), which are available for [hls.js](https://github.com/apivideo/api.video-hlsjs-analytics), [video.js,](https://github.com/apivideo/api.video-videojs-analytics) [Android](https://github.com/apivideo/api.video-android-player-analytics), and [iOS](https://github.com/apivideo/api.video-swift-player-analytics).

&nbsp;
    

Once you fulfill these requirements, you’ll immediately be able to retrieve analytics using both methods discussed in this tutorial.

&nbsp;

*Note that when using api.video’s **Sandbox environment**, the extent of data that you can retrieve is limited to the last 24 hours.*

## The no-code way

By far the easiest method to get analytics for your videos and live streams is through the [Analytics page in the api.video dashboard](https://dashboard.api.video/analytics). The dashboard shows the number of play events grouped by some of the most useful dimensions that can help you answer questions like:

&nbsp;

- Which videos or live streams are the most popular this week?
- What time of the day is your content most engaging?
- Which country are most of your viewers based in?
- Which devices, browsers, and operating systems are viewers using the most?

## The integrated way

For those that prefer a more hands-on approach, we’ll dive into how you can leverage our API to retrieve analytics data and build out some typical Analytics use cases.

### 1. Set up the **api.video client**

Let's initialize the [api.video client SDK](https://docs.api.video/sdks/api-clients) in your environment, using an example **in Node.js**:

### 2. Create a request

The client SDK will require your API key, which you can find [in the dashboard](https://dashboard.api.video/project-settings/api-keys). Check out the [Authentication guide](https://docs.api.video/reference/authentication-guide) if you want to understand the different authentication methods you can use with api.video.

&nbsp;
 

Let’s say you want to know **which one of your videos performed the best in the last week**:

Notice that we’re passing in `from` and `to`, which determine the time interval that you want to analyze. We’re also adding `videoID` as the dimension, which will give you result for every `videoID` available in your project.
&nbsp;
 

Here’s an example response payload for this request:

In the response, `value` shows values for the `dimension` we set in our request. In this case, since we requested `dimension=videoId`, each `value` field in the response returns a video ID.
&nbsp;
 
`plays` returns the number of play events.
&nbsp;
 

Now let’s try a different dimension: let’s see **how a specific video performs across different countries** where your viewers are based.

Notice that we’re passing `from`, which determines the starting time of the data analysis. We’re adding `country` as the dimension, which will give you results for every country where you had viewer engagement. We’re also adding a video’s ID value as the `filter`, which will filter results in the response payload and only shows analytics for the specific video that the ID belongs to.
&nbsp;
 

Here’s an example response payload for this request:

Check out the **complete list of dimensions** and **example response payloads** for both success and error cases in [the API reference](https://docs.api.video/reference/api/Analytics).

### 3. How to use this data?

When building an application or website where you serve videos or live streams, you can find some creative ways to leverage analytics data:
&nbsp;
 

- Create **data visualizations** for your users. This could include graphs and charts showing views over time, peak viewing periods, or geographic distribution of the audience.
-  **Localize Content.** Use geographic data from play events to tailor content to specific regions, accommodating regional preferences or languages.
- **Create recommendations**. Find the most popular, or even the least popular videos and show them as recommended videos for your viewers.

## Conclusion

With api.video’s Analytics solution, you're not only delivering content; you're unlocking a world of data that helps you connect more meaningfully with your audience. Whether you're aiming to expand your reach, tailor content to specific regions, or simply understand your audience better, api.video’s Analytics is your gateway to smarter content strategy.


&nbsp;


To start using api.video and see how this works, [sign-up](https://dashboard.api.video/register) for a free sandbox account now.

How api.video’s Analytics can help you enhance your content strategy

api.video Analytics helps you enhance your content strategy

small_Blog_Analytics.png

thumbnail_Blog_Analytics.png

Blog_Analytics.png

If you want to advertise on a budget, it's easier when you know where your content is already succeeding. With api.video's analytics, you can see what cities and countries viewers are visiting your site from. This kind of information can give you a general sense of where you might want to spend (or not spend) your advertising dollars. 

You could view your data in a list, but it might be faster if you represented the data visually with something like a map that shows viewer density per city. Today, we're going to use OpenLayers, Observable, and api.video's data analytics for a demo account to retrieve what we need to plot all the cities viewers watch live streams from on a map. We'll represent how many sessions (viewers) there are per city with a circle that has a bigger circumference if there's more viewers, and a smaller one if there's less viewers. We won't fill in the circles so we can see markers for all overlapping cities. 

Let's start mapping! 

A map showing viewer density per city using api.video data, Observable, Geocoding, and Open Layers

apivideomapmarkerslivestream.jpg

## Prerequisites 
For this tutorial, you'll need: 

* api.video account - [Sign up for api.video here](https://api.video).
* Observable account
* OpenCage Geocoding API account 
* requests, csv, pycountry, opencage, and pandas libraries for Python 

If you don't know JavaScript, or the version of it that Observable's using, you don't have to. This tutorial will explain how to configure your map in a way where you don't have to know the JavaScript. If there's interest in having the JavaScript content explained more, let us know in our [community forum](https://community.api.video)! We can explain everything in a future post. 

## Build Your Data File 
In this section, we'll create the data file we want to use with our map. The code sample will: 

* Authenticate with the api.video API.
* Retrieve a list of all our live streams.
* Retrieve all sessions for each live stream and for each session, create a dictionary containing the live stream title, the session ID for the session, the city, the country, and we'll also add the latitude and longitude coordinates using the OpenCage Geocoding API.
* Write each dictionary to a line in a csv file that we can then use in a pandas dataframe. 

Here's the code:

In the code we choose to use 'open with' to open the csv file we'll write to, because this method will close the file for us when it's done writing everything. We also use the dictionary writing feature of the csv module for Python. This allows us to create a header row listing all the columns we want. We can then create a dictionary where every key matches a column title. Whatever we set as the value will be written to the csv file as a row. 

We add latitude and longitude for every city in our file, and then we output to the file ls_session_data.csv. The next step is to add our CSV file to a pandas dataframe. 

## Create a Dataframe With Your CSV File 
We convert our brand new CSV file to pandas so we can manipulate the data. There are other ways you can do this, but once you have the hang of pandas, you can do a lot with it. 

Here's the code for moving our csv file to pandas, grouping everything and then outputting it back to a csv file we call 'country_lat_lon.csv:

Now we're ready to build our map. 

## Configure Observable 
In this section, we walk through how to get your map set up on Observable. If you haven't done so, sign up for an Observable account. Then do the following: 

1. Navigate to our Observable notebook [Where api.video Live Streams Are Watched](https://observablehq.com/@erikkai/where-api-video-live-streams-are-watched). 
2. Click the three dots in the upper right corner. A menu opens. 
3. From the menu, choose **Fork**. Now you have your own copy of the map to edit and play around with. 
4. Click the three dots in the upper right corner again and choose **File attachments**. 
5. Delete the existing copy of **country_lat_lon.csv** and upload your copy. Don't try to upload expecting an overwrite - it will add a 1 at the end of your file. Then you will have to tweak the file name in the code. (Where you do that is explained in the Observable notebook if you decide to go that route instead.) 
6. Make sure your data is loaded. You can check if anything needs an update by looking for a solid blue triangle in the upper right corner of the cells on this page. Click any you see. 
7. Your map should display, showing viewer density by city through the size of the circle used as a marker.

## Tweaking Observable and OpenLayers
You can tweak this map lots of different ways, or go back to the one it's forked from and tweak that instead. Some suggestions for areas to try changing things: 

1. Go to the Set the Center section. The array listed shows a pair of coordinates that are longitude, then latitude. If you change these, you can change the center the map starts out with. 
2. Go to the Define vectorSource, Programmatically Add Markers section. In the block of code that starts **data.forEach** you can change how big or small the circles are by changing what you multiply Count by. This creates the radius of your circle. 
3. Go to the Add Your Data section. If you click the three dots to the left of **data = Array(45)** you'll be able to see the import code. If you want you can use a different file name, or change the code to upload a different kind of file for use in the project (though that might have more effects on the rest of the code). 
4. You can see different types of markers you can add by looking at another user's post about using OpenLayers - [Fork of Openlayers to put some markers/features on](https://observablehq.com/@chonghorizons/fork-of-openlayers-to-put-some-markers-features-on). 

If you try a map, be sure to share it with us in our community forum! We'd love to see what you do with your data. 

Use api.video Analytics to mark viewer density with Observable

medium_apivideomapmarkerslivestream.jpg

small_apivideomapmarkerslivestream.jpg

thumbnail_apivideomapmarkerslivestream.jpg

Api.video Analytics: Add markers representing viewer density per city to a map with Observable

A great way to see at a glance how many viewers you have per country is with a choropleth map. It probably sounds like I'm talking about some weird kind of plant you've never heard of, but chances are you've looked at lots of choropleths before. It's a map that's used to represent statistical data by shading different geographical areas with different colors that represent a certain number of people, items, or whatever else. If you're still a little confused by that explanation, a picture is worth a thousand words, so here's an example of a choropleth map: 

examplechoroplethapivideo.jpg

The map we're displaying here shows you population density per square mile in the U.S. The value of a choropleth map, is you can quickly understand data. If you had to look at a list of density numbers by state, you might take extra time to scan and find the biggest numbers. With this example map you can see that the darker colors represent higher densities and the lighter colors represent lower densities. Armed with that knowledge you can easily see which states have the highest population densities by color. 

We can create the same kind of map for api.video! In this tutorial, we'll talk about grabbing the data you'll need, and then how to use it with Observable to turn it into a map. 

## Prerequisites
For this tutorial, you'll need:
* api.video - [Sign up here](https://api.video).
* Observable account - [Sign up here](https://observablehq.com).
* requests, csv, pycountry, and pandas libraries for Python 

Let's start coding! 

## Retrieving Analytics Data
There are lots of ways to retrieve analytics data, so while we'll post a code sample here, you may want to change it for your data. Some tips to keep in mind are: 

* Take a look at a JSON response for analytics before building anything to grab the data. You can see responses here - [Tips for Working with api.video Analytics Data](https://api.video/blog/tutorials/tips-for-working-with-api-video-analytics-data/). You can also figure out how you want to design everything. 
* For Python samples, if you know you have a lot of videos, livestreams, and/or sessions, you will need to handle pagination yourself. 
* If you know what you want to do to start with, you can retrieve just that data. We added a few extra things for reference, but otherwise pared down the available data.
* Decide how often you want to update your data. 

To keep things simple, this time we're just pulling the data and writing it to a CSV file. In future tutorials, we'll learn how to create a database that periodically updates itself with your analytics data. 

Here's the code we used to: 

* Get all the analytics data and flatten the JSON. Flattening JSON means taking it out of its nested structure, so each set of information about a video, livestream or a session fits into one row of data. 
* Add the three letter country code for every country. If one can't be retrieved because the country is unknown, add '---.' 
* If the city or country isn't known, put 'unknown.'
* Add the title to a video or live stream for our reference when reviewing the csv
* Add the assetID and sessionID for our reference when reviewing the csv
* Write a row to a csv file for each session

If you don't like what we choose to extract, you can add or remove by tweaking the code. 

We will be using the file we generate to create the choropleth.

After you run the code sample, you should have a csv file that contains details about all of your video and live stream sessions. It takes awhile to run if you have a lot of data, so if it seems like it's stuck, it's not. It can take upwards of 15 minutes if you have lots of data to crunch through. Take a break or work on something else while everything is retrieved. 

## Add Your CSV to a Pandas DataFrame
The next step is to take your CSV file and convert it into a pandas dataframe. Pandas is a software library used for data science activities. It makes it easier to do a lot of time consuming, repetitive tasks you need to do with data like cleansing, performing mathematical operations on columns, filling information in, removing data, inspecting it, and lots more. It also has a steep learning curve, but don't worry if you've never used it, we're providing a code snippet for working with it. 

In this code snippet, we create a dataframe in pandas. Then we drop everything and grooup information so we get a table in CSV format with two columns: ISO_A3 and Count. That's all we need for our map! If you need to get the data back, it's still in your CSV file and you can use it in pandas to group information however you want. 

We're going to use this new csv file- 'choro.csv'- to build our choropleth. 

## Configure Your Choropleth in Observable
Here's where we walk through using Observable. We're going to switch over to using something similar to JavaScript. Most of it's set up for you, and the sample map we've created will show you where your data goes. 

1. Navigate to Observable and log in (or sign up if you didn't already). 
2. Navigate to my [sample choropleth](https://observablehq.com/@erikkai/viewers-of-my-videos-and-live-streams-around-the-world) (built from Mike Bostock's cool [Hospital Beds](https://observablehq.com/@mbostock/hospital-beds) choropleth).



choropleth, apivide, api.video, data analytics

choroplethapivideo.jpg

3. Get the final CSV file generated with the instructions (for Python) - 'choro.csv'
4. Click the three dots in the upper right corner. Click **Fork**. You want to do it this way, so you get this version of the file and not the original hospital beds map. We've tweaked a couple of things, and if you don't want to do tweaks yourself and instead see everything work as described, you want to fork this project.
5. Click the three dots again. Click **File attachments**. You'll open an upload panel.
6. Click **Upload**.
7. Browse for your copy of '**choro.csv**' and upload it.
8. Run everything, it should work and show you a map. Based on how many viewers you have, this implementation will automatically divide everything into colors on the scale displayed at the top.

You can make your own version of the map and then publish a notebook that you can share anywhere, showing off a beautiful map of where you have the most viewers! 

 Build a Choropleth Map with api.video Analytics

medium_choroplethapivideo.jpg

small_choroplethapivideo.jpg

thumbnail_choroplethapivideo.jpg

Api.video Analytics: Build a Choropleth Map (and find out what one is)

Video analytics can tell you a lot about how people are watching your video, especially if you decide to dig into player sessions. With api.video's [analytics endpoint](https://docs.api.video/reference/api/Analytics) you can figure out details like where people fast forward, or rewind your video. This information can be used to help you determine things like:
* Whether something is confusing or boring
* Whether something is interesting or entertaining

...and more! 

For this article, I decided to pull analytics for a popular api.video demo called [Upload a video to Discord](https://a.video/works/upload-a-video-to-discord). 

## Pull Analytics Data for a Video
If you know what video you want to pull analytics for, it's pretty easy to grab this information: 

1. Open your dashboard by clicking **Login** on the [api.video](https://api.video) homepage and logging in if you are not logged in to api.video. 
2. Navigate to [your dashboard](https://dashboard.api.video/).
3. Click on the video you want analytics data for. 
4. On the video's page, there's a copy link section that will contain a video link. It will look something like: `https://embed.api.video/vod/vi5PBib80QrC8q73AekJqNDH`. Get the videoId, which is the part that comes after **vod/**. 

NOTE: You could also collect this information programmatically. To do that, you'd send a request to the [videos](https://docs.api.video/reference/api/Videos#list-all-video-objects) endpoint. You'd look through the list returned, pull the videoId for the one you wanted, and continue on. 

5. After you have your videoId, you're going to want to retrieve an exhaustive list of player sessions for your video. The code for that is: 

For our data file, for each row we list the sessionID, what type of action was taken, when the session with the video first started (emitted at), and then three columns - at, from, and to. Some of the action types don't use some of these last three columns.

## Get Familiar with Your Data
Now that you have your csv file containing all the sessions for the video you selected, it's time to start thinking about how to analyze it. You can see a lot of interesting information: 
* pause - when someone pauses a video 
* resume - when someone resumes a video
* ready - when the video is at the start position
* play - when someone starts the video
* end - when someone watches to the end of the video
* seek.backward - when the video winds backward
* seek.forward - when the video winds forward

In our table, a sample row for each will look like: 

pause
`-sessionID-, pause, 2021-02-25T09:57:14+00:00, 45, not, not` 

What we can see from this sample row, is that someone paused their video 45 seconds in. If the row right after pause isn't resume, we can check if the sessionID is different. If it is, we can be sure that whoever was watching the video, stopped watching at 45 seconds. Who would do such a thing? There's an extra 5 seconds of video after that! As it turns out, if you watch the video here: [https://a.video/works/upload-a-video-to-discord](https://a.video/works/upload-a-video-to-discord) you can see that by 45 seconds, Doug successfully completed the task he's teaching with the demo. The video runs on Discord. If you were satisfied with the demo, you might pause the video and then leave, or close the tab (which would count as a pause to api.video's analytics). 

resume
`-sessionID-, resume, 2021-02-25T18:10:28+00:00, 25, not, not` 

The resume action will usually occur right after pause, or after a seek.forward or seek.backward action. This action is anytime the video is stopped, and you press play. If your video is at the very start, clicking play doesn't register as a resume. 

ready
`-sessionID-, ready, 2021-02-25T14:48:49+00:00, 0, not, not` 

Ready appears when you open the video and you haven't started playing it yet. If you see ready and then you see a different sessionID, you know the user reached the video, then decided for some reason not to play it. You will need other contextual data to guess why that might be.

play
`-sessionID-, play, 2021-02-25T18:10:20+00:00, 0, not, not`

The play action occurs at the start of the video, when the user presses play. This can be a useful event to check for since if you don't find it in a session, you can be sure the user didn't start the video. 

end 
`-sessionID-, end, 2021-02-27T17:30:18+00:00, 50, not, not`

The end action indicates that the user watched the video to the very end. This can be useful if you want to filter through sessions to see what percentage of sessions reach the very end of the video. 

seek.backward
`-sessionID-, seek.backward, 2021-02-27T14:53:02+00:00, not, 35, 29`

Something to watch for is where users wind back. If you're teaching them something, they might be winding back because they don't understand a concept, or they can't clearly see something in the video. They could also wind something back because it's interesting, or they weren't paying attention and need to rewatch it. 

seek.forward
`-sessionID-, seek.forward, 2021-02-26T09:52:56+00:00, not, 29, 38`

Seeking forward can mean a lot of things. If you've made an instructional video, a user could seek forward to surf through the video and see if they can find the information they need more quickly. They could seek forward because a concept was well explained, and they're ready for the next concept or step. It could also be because they feel bored. It will depend on the video and your analysis of the content vs. the behavior. 

## Grooming the Data
To do find patterns in your data, you can start trying to filter it to see if you find something. Here's a few ideas I started with: 

* See if there's anything repetitive that stands out when I scroll through the csv that gives me ideas. 
* See if there's anything weird that stands out. 

NOTE: Obviously looking at a table of data when there's tons of entries isn't the best way to review your information. It's a starting point that acquaints you with what it looks like and what you have. You should always make sure to come up with questions to investigate where you can filter content to answer them or visualize your content. 

* Come up with ways to filter things that might display a pattern. This would be where you ask questions like, how often do people seek backwards or forwards? What do they seek backwards and forwards across the most? 
* Come up with ways to count things that might yield interesting information. For example, how many sessions are there where people watch the video all the way to the end? 

### Browsing the Data
As luck would have it, when I started browsing the data I did notice something I thought was odd. There were a lot of instances where it looked like a user wound the video back from the very end to the very beginning. The lines of data looked something like this: 

`-sessionID-, seek.backward, 2021-02-28T15:49:44+00:00, not, 50, 0`

Why, I wondered, would a user want to rewind all the way to the beginning? Examining the data, I noticed something else- the seek.backward like this happened after the end event in the same session.

`-sessionID-, end, 2021-02-28T15:48:42+00:00, 50, not, not`

I checked and discovered the player for this project is set on loop. I didn't know before, but now know that if your player is looping, the loop is shown as two events - first, end. Second, seek.backward to 0. Instances where I found this in the data were spots where someone left the video running and it just looped around again. 

### Filtering the Data
To filter the data, I decided to start with an easy question. Out of the total number of sessions I pulled, how many sessions did a user watch the video all the way to the end? 

NOTE: You need to have pandas installed in your Python environment.

videoanalyticsapivideo.png

From this data, we get answers to questions I have not asked yet! Starting with the first question, what percentage of users watch all the way to the end? To answer this, we must figure out how many sessions we have total. That's easy - we know that 'ready' only occurs once per session, and indicates that a video is ready to be played. From our chart, we can see we have 725 instances of ready. So that means 

Answer: 25.5% of users! That's great. Especially because in an instructional video, people often learn the concept, and leave immediately. The end of this video is an interesting shot of bells chiming in a church, which 25% of viewers liked enough to stay for, even though it could be argued that you learn everything you need about this demo by about the 42 second mark - where you see the video successfully play on Discord. I would interpret this statistic as an indication that the content is educational and entertaining. 

We also learn something that might seem a little strange, we have 725 sessions, but of those 725 sessions, people only played the video 582 times. That means about 80.28% of users watch the video, but about 19.72% don't. That might seem weird - who goes to a page to see a demo then says nope nevermind? A possible answer lies in the page the video is shown on. Here's an image for you: 


discorddemoapivideo.png

So we can see the video here, but check out the choices we offer below the video - Blog Post and Github. As you may know, some developers don't want to read blog posts or watch videos. They just want a code sample. So a possibility is they come here for the demo, then they see we offer the code, decide that's what they prefer, and away they go! 

What I could maybe be looking at here is the answer to the question 'What percentage of developers prefer a code sample to a written tutorial or demo?' (specifically for our company, don't quote me on this one). I could pull more of api.video's demo analytics and see if the percentage stays consistent across the demos. With a tool like HotJar, I could figure out if we have a lot of users that immediately click on that GitHub link or not, and start building a case for my hypothesis, or disproving it.

Because we're creating educational content, I could maybe use the ~20% statistic to make a case for always including code samples for our demos on github. You could use this information other ways too. If your video was a movie or a short film for example, you might want more people to watch the video than 80%. Maybe it would lead you to test other page designs, or changing the thumbnail for your video to make it more interesting to everyone. 

Okay well this was fun. Let's try some more filtering and a little bit of visualizing. 

### Visualizing the Data
There are lots of ways to visualize your data. For this post, I decided to keep it simple, and use a graph you can create with plotly. But before we get to the tools, how about the question? I decided to plot all instances where somebody is seeking forward or backward. 

For my first try, I thought, why not use the index to plot each instance of winding forward and backward, and I'll use colors. I narrowed my data down to just rows that contained seek.forward or seek.backward. Here was my code:

In the sample, I take all the master file with all my sessions for this video, and then I choose only rows that contain seek in the type. I output this into a new file 'discord_seek_sessions.csv'. 

Now it's time to try making some kind of chart. I went with something simple. I thought maybe I can use the index to represent separate events. Each event gets its own index marker. It came out like this: 

bekindrewindapivideo.png

There's a lot going on. There's so many entries, they scroll off the top and bottom right side of the page. If it's not clear, the legend on the right represents the time interval in seconds someone used seek.forward or seek.backward. The line represents the color that will be displayed in the graph. On the graph, across the bottom you can see the time in seconds. Up the left side, is the index that went with the event displayed. 

Let's make this better. The first thing I tried, was regrouping everything. I gave a unique index to anything with the same session ID and seek direction. That way each session would have two bands where you could see the lines. It didn't improve the chart's clarity, but the code for it is neat and will help us later, so I'm going to share that for you here: 

If you ever need to assign an index value based on a group, this code will help you! But it didn't help with our situation. That led me to the next idea, what if I split the sessions into separate dataframes? or csv files, depending on how you prefer to do things? 

This yielded a bit more clarity. Also I chose to put the data into separate csv files, this is the code for that:

Checking out the different files in my chart, I used the groupby trick I just told you about. Because there is only one type of action per chart, it places every instance of a particular seeking action on one line. A little less busy, but not a big improvement. 

The next thing I thought of was going back and counting how popular it was to wind either forward or backward at any point in the video. The code for that is pretty simple, and I decided to use it for winding forward: 

Now it's getting interesting. What if I make a chart of the most popular place to forward.seek from? It looks like it's about 33 seconds into the video. (See?) 

forwardseekapivideo.png

Let's make the chart now! We can reuse some code from earlier, and filter for instances when from = 33. 

cleanedupdata.png

Why is seeking forward so popular here? If you watch the video, you'll note that this is the part where Doug walks through using Discord. If you are using the tutorial because you like Discord, it's possible some users are really familiar with Discord already. So during this section, they seek forward to find out what comes next. When it gets to where the video plays, 25% watch the video, everyone else says aha! I've learned how to do this now I will go implement what I've learned etc. 

You can repeat this process with other areas in your video. For example, in this video, there's high seek forward rates from around 15 seconds through to 22 seconds. In the video, this is the part where you wait for an upload to complete. If you were trying to optimize the video or edit it, you might make a case that part of this section could be edited out. 

While we're applying this to an educational demo, you could easily apply this kind of simple research to short films and movies. Find out where people fast forward to learn if a section of the film isn't working the way you planned. If someone keeps winding a section back to rewatch it, maybe it's because it's an incredible scene, and you can make sure to do more things a similar way in the future. 

Hope this was a fun start to analyzing your content! See you next time.

Using analytics to analyze where to edit a video

large_bekindrewindapivideo.png

medium_bekindrewindapivideo.png

small_bekindrewindapivideo.png

thumbnail_bekindrewindapivideo.png

Leverage api.video’s Analytics to enhance your content strategy

webhooks

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

NodeJS

One of the most satisfying features of livestreaming is seeing a live counter of how many people are watching your live stream.  In this demo, we’ll build a counter that gives a real time count of the number of viewers watching a live stream.

## api.video livestreams

Each livestream at api.video can be used over and over. It is a conduit for your livestreams.  There is a RTMP url that you use to send your livestream to api.video, and a playback url that you can embed in your website.  When you look at a livestream on your [api.video dashboard](https://dashboard.api.video/), you’ll see all the connection details (some are obfuscated in the screenshot) to connect your livestream. 

large_screenshot-2021-07-22-at-06-12-10.png

medium_screenshot-2021-07-22-at-06-12-10.png

small_screenshot-2021-07-22-at-06-12-10.png

thumbnail_screenshot-2021-07-22-at-06-12-10.png

viewer-count-video.png

Right underneath the thumbnail of the livestream, you can see a viewer count.  In the screenshot above it is at 632. That is the count of historical views for this livestream - a sum of all the views for every livestream that has been run. While this is an interesting stat, this is not exactly what we want to see during a livestream.

This NodeJS function takes your liveStreamId, and calls the analytics endpoint to get the total number of sessions that have occurred for that live stream:

```
function getLiveSessionCount(liveStreamId){
 
   return new Promise(function(resolve, reject){
       console.log(liveStreamId);
       var pageSize=1;
       var currentPage = 1;
       params = {
           "liveStreamId": liveStreamId,
           "pageSize":pageSize,
           "currentPage":currentPage
       }
       //get all sessions for livestream
       var sessionList = client.rawStatistics.listLiveStreamSessions(params);
       sessionList.then(function(liveSessionList){
           //get total sessoin
           var sessionCount = liveSessionList.pagination.itemsTotal;
           console.log("live sessions" , sessionCount);
           resolve(sessionCount);
       }).catch((error) =>{
           reject(error);
       });
   });
}

```

## Counting the views

To get an accurate count of viewing sessions during a livestream, we need to grab the livestream count when the stream starts (all of the views PRIOR to the current stream).  As the stream progresses, the number will increase, but a simple difference ```currentCount - startCount``` will provide the number of sessions that occurred during the current stream.

### Live stream webhooks

In July 2021, we launched 2 new webhooks: ```live-stream.broadcast.started``` and ```live-stream.broadcast.ended```.  These webhooks announce whenever one of your live streams begin/end broadcasting. 

When the ```live-stream.broadcast.started``` webhook fires, our webhook listener identifies that a live stream has started.  Then it calls the getLiveSessionCount function to get the starting count of sessions.

```
app.post("/receive_webhook", function (request, response) {
   console.log("new video event from api.video");
    let event = request.body;
   let body =request.body;
   let type = body.type;
   let emittedAt = body.emittedAt;
   webhookResponse = "";
   if(type =="live-stream.broadcast.started"){
       liveStreamId = body.liveStreamId;
       liveStreamStatus = true;
       webhookResponse = "event: " +type+ " at: "+ emittedAt+ " LiveStream,Id: "+liveStreamId+ "  has started.";
      
       //change the broadcasting status in the JSON pbject
       broadcastingStatus[liveStreamId]=liveStreamStatus;
       //TODO - get the number of views at start
       startViews = getLiveSessionCount(liveStreamId);
       startViews.then(function(startcounter){
           console.log("number of views when broadcast starts", startcounter);
           viewersAtStartOfStream[liveStreamId] = startcounter;
           webhookResponse = "event: " +type+ " at: "+ emittedAt+ " LiveStreamId: "+liveStreamId+ "  has started. There have been "+startcounter+" at the beginnig";
 
       });
      
    } else if (type =="live-stream.broadcast.ended"){
       liveStreamId = body.liveStreamId;
       liveStreamStatus = false;
       broadcastingStatus[piLiveId]=liveStreamStatus;
       webhookResponse = "event: " +type+ " at: "+ emittedAt+ " LiveStreamId: "+liveStreamId+ "  has stopped.";
    }
  
   //console.log(headers);
   console.log("response",webhookResponse);
 
  
   response.sendStatus(200); 
 });


```

Now, as the streaming progresses, the website polls /getLivecount every three seconds:

```
// Send list of the new count of viewers every x seconds
app.get("/getLivecount", function (request, response) {
 
 
   var LiveId = request.query.live;
   console.log("LiveId", LiveId);
   console.log(viewersAtStartOfStream);
   startCount = viewersAtStartOfStream[LiveId];
   console.log("startCount", startCount);
   //we have liveid get new user count
   var currentCount = getLiveSessionCount(LiveId);
           currentCount.then(function(currentWatchCount){
 
               console.log(startCount + " " + currentWatchCount);
               numberOfWatchers = currentWatchCount - startCount;
               console.log("numberOfWatchers", numberOfWatchers);
               response.send("There are " +numberOfWatchers + " watching this stream!");
           }).catch((err) => {
               console.log(err);
           });
 });

```

And this returns the difference from the start of stream (stored in an array on the server), and the current count.  Voila, a simple view counter!

##  Conclusion

In this demo, when the live stream begins broadcasting, we utilize the [live stream started webhook](https://docs.api.video/reference/api/Webhooks#create-webhook), which broadcasts that the stream has started. We determine the ‘seed’ number of sessions using the [Live stream session analytics](https://docs.api.video/analytics/overview). Now we know the “0” for this live streaming session.

We can call the same endpoint every 3 seconds and report the growth in the number of sessions.  Each one of these is a new loading of the live stream video player - counting as a new viewer of the stream. This is then added to the page to indicate how many viewers are watching the live stream.

This demo is live at [watch.a.video/broadcast](​​https://watch.a.video/broadcast?streamId=li400mYKSgQ6xs7taUeSaEKr). To begin the stream, head over to [livestream.a.video](https://livestream.a.video) and begin the stream. To grow the number of viewers, you must open [watch.a.video/broadcast](​​https://watch.a.video/broadcast?streamId=li400mYKSgQ6xs7taUeSaEKr) in multiple incognito/private browser tabs (since the session is browser window based).

Try it out, and tell us what you think! If you’d like to look at the code to modify for your app, it is live on [Github](https://github.com/dougsillars/watchLivestream).


Count your live stream viewers with api.video

thumbnail_counter.jpeg

counter.jpeg

api-video-blog-product-updates.png

Product updates

In today's fast-paced digital landscape, the explosive growth of videos has revolutionized the way we consume information, connect with others, and engage with brands. Whether it's on social media, streaming platforms, or corporate websites, videos have become an integral part of our online experience.

&nbsp;

And behind the captivating visuals, lies a treasure trove of data waiting to be unraveled. Today, we recognize the importance of data-driven insights in shaping strategies, enhancing user experiences, and achieving desired outcomes. By meticulously examining viewer behavior, engagement patterns, and demographic insights, we can uncover actionable intelligence that allows us to personalize experiences and unlock untapped potential.

&nbsp;

For this very reason, **api.video has recently launched real-time video Analytics which allow you to dive deeper into the numbers behind your videos**. Let's learn a little more about it below. 

## How does Analytics help you?

Analytics help you get in depth insights for your videos and live streams. It will help you answer questions like: 

&nbsp;

- Which videos are being viewed the most today or this week or this month?
- Where in the world is my content being viewed?
- Which devices, browsers, and operating systems are viewers using the most?
- What time of the day is my content most engaging?

## What do you get with Analytics?

Analytics provide you engagement data related to your videos and live streams. For instance, you can:

&nbsp;

- get the number of plays for a specific video for a period like the current day, current week or the last 30 days
- get the number of plays by country
- get the number of plays for specific devices, browser agents, and operating systems.


## How does it work?

Api.video's solution uses playback data to analyze and segment your viewers. 

&nbsp;

- Numbers are automatically collected for every video or live stream if played with the built-in api.video player
- Each interaction with the video content generates a play event
- Play events are reported in real time and can be instantly viewed on the api.video dashboard or retrieved through the API
- Third-party players are also supported through the provided analytics plug-ins (any HTML5 player that supports event-based reporting)
- The data is retained for 30 days

&nbsp;


![pexels-lukas-590020.jpg](https://datocms-bucket.s3.eu-central-1.amazonaws.com/pexels_lukas_590020_4c03e9015f.jpg)

## The best part - it is all real-time data!

Yes, you read that right! All the data you see under the Analytics section is collected and computed in real-time. We all know time and speed = money, which is why this data will be available immediately for your usage and analysis. This real-time data can be especially useful if you are using it to keep track of live stream engagement or manage a lot of user-generated content.

## How do you start using Analytics?

To start viewing data, you can use the dedicated API endpoint or check the dedicated page on the api.video dashboard if you are looking for convenient access and viewing.

&nbsp;

Check out the detailed guide in our [analytics documentation](https://docs.api.video/analytics/overview) for more details on this, and our [FAQ section](https://help.api.video/en/articles/7983849-analytics) for some common questions you may have. In production, you can activate Analytics from your Dashboard. You will need to be the owner of the workspace account to do so.

&nbsp;

__[Sign-up on api.video](https://dashboard.api.video/register) now and get the complete toolkit for your videos at one place!__

Introducing Analytics at api.video for better video insights

Analytics at api.video for better video insights

large_video_meets_data_not_rounded.jpg

medium_video_meets_data_not_rounded.jpg

small_video_meets_data_not_rounded.jpg

thumbnail_video_meets_data_not_rounded.jpg

video_meets_data_not_rounded.jpg

How many people have watched my video?

How much of my video are people watching?

Is there a common abandonment time?

Are my users skipping ahead in the video?

These are questions that can be solved with api.video's [analytics](https://docs.api.video/reference/api/Analytics).  

## Now available with external players

api.video offers video encoding, hosting, delivery and analytics.  If you do not want to use our player (or already have an integration with another player), you can use your [3rd party player to deliver the video](https://api.video/blog/tutorials/using-api-video-with-external-video-players/). 

Until now, when you used an external player, you lost the opportunity to gain any insights from our analytics engine. We have now launched libraries for [videojs](https://github.com/apivideo/videojs-player-analytics), [hlsjs](https://github.com/apivideo/hlsjs-player-analytics), and a general [analytics package](https://github.com/apivideo/player-analytics), allowing you to integrate api.video analytics into your customized 3rd party video player!

## How does it work?

Let's look at an integration with videoJS. Here's a simple page that loads a video from api.video into videoJS, (and has added in analytics):


```
<head>
  <link href="https://vjs.zencdn.net/7.10.2/video-js.css" rel="stylesheet" />
  <script src="https://vjs.zencdn.net/7.10.2/video.min.js"></script>
  <script src="https://unpkg.com/@api.video/videojs-player-analytics"></script>

  
  
</head>

<body>
  <video
    id="my-video"
    class="video-js"
    controls
    preload="auto"
    width="1280"
    height="720"
    poster="https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg"
    data-setup="{}"
  >
    <source src="https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8" type="application/x-mpegURL" />
    
      To view this video please enable JavaScript, and consider upgrading to a
      web browser that
      <a href="https://videojs.com/html5-video-support/" target="_blank"
        >supports HTML5 video</a
      >
    </p>
  </video>

  <script>
             videojs.registerPlugin('apiVideoAnalytics', VideoJsApiVideoAnalytics);
            
             var player = videojs('my-video');
	         player.apiVideoAnalytics();
			 
         </script>
</body>
```

To add analytics, we add the script in the head of the document:

```
 <script src="https://unpkg.com/@api.video/videojs-player-analytics"></script>
```

and then to add the analytics engine, we add the JavaScript at the end of the page:
* registering the api.video analytics plugin
```
 videojs.registerPlugin('apiVideoAnalytics', VideoJsApiVideoAnalytics);
```
* assigning a variable to the player
```
 var player = videojs('my-video');
```
* connecting the player to the analytics plugin
```
player.apiVideoAnalytics();
```

and that's all there is to it!

## Can I add metadata to the analytics?

Yes! If you replace: 

```
player.apiVideoAnalytics();
```

with:

```
      player.apiVideoAnalytics({
        metadata: {
          player: "videojs"
        }
      });
```

you can collect [dynamic metadata](https://api.video/blog/tutorials/dynamic-metadata/).  In this case, I am assigning the value videojs to the player variable.  Now, whenever anyone watches a video using this videoJS player, it will be recorded in the dynamic metadata as such (so I can break down the playback across different devices).

Querying the analytics, we can see this in action:


```
		{
			"session": {
				"sessionId": "ps4ZrdWqAR8mevHi4IwHoACf",
				"loadedAt": "2021-04-01T11:07:25+00:00",
				"endedAt": "2021-04-01T11:07:25+00:00",
		*		"metadata": [
					{
						"key": "player",
						"value": "videojs"
					}
				]*
			},
			"location": {
				"country": "United Kingdom",
				"city": "Chesham"
			},
			"referrer": {
				"url": "https://jsfiddle.net/",
				"medium": "unknown",
				"source": "unknown",
				"searchTerm": "unknown"
			},
			"device": {
				"type": "computer",
				"vendor": "unknown",
				"model": "Other"
			},
			"os": {
				"name": "Mac OS X",
				"shortname": "Mac OS X",
				"version": "11.2.3"
			},
			"client": {
				"type": "unknown",
				"name": "Chrome",
				"version": "89.0.4389"
			}
		}
```

## Conclusion

We are working to make api.video integrate easily into your infrastructure.  If you use a 3rd party player, you are no longer prevented from using our analytics to study the playback of your videos.

Grab the appropriate library, and try it today!

[videojs](https://github.com/apivideo/videojs-player-analytics)

[hlsjs](https://github.com/apivideo/hlsjs-player-analytics)

[General analyitics package](https://github.com/apivideo/player-analytics)

New feature: Analytics libraries for 3rd party video players!

43160471697fbafef276c.jpg

In the classic movie *Field of Dreams*, a mysterious voice whispers to Kevin Costner “if you build it, they will come.”  


<video autoplay muted loop>
		<source src="https://media.giphy.com/media/gZuxOq7zSL5DO/giphy.mp4">
</video><br/><br/>


His belief of this statement completely transformed his life and drove him to build a baseball stadium in the middle of a cornfield in Iowa… and they came…<br/>


<video autoplay muted loop>
		<source src="https://media.giphy.com/media/z3WMjg3hu3ce4/giphy.mp4">
</video><br/><br/>


## If you Stream it...

You've created some awesome videos, and uploaded them to api.video.  Great work - it looks awesome.  

Here is a video that we posted in our blog post announcing our new video player:

<iframe src="https://embed.api.video/vod/viTLpKB231ATWOWjkHgi9bf#autoplay#loop" frameborder="0" scrolling="no" allowfullscreen=""></iframe>
<br/><br/>

## ...Who will come?

Eventually you want to know, how many people came to see my video?  What can I learn about them? Enter api.video’s powerful [video analytics](https://docs.api.video/reference/api/Analytics) API. Using the API, we can transfer all of the view data form our videos into our favourite database, and learn about the viewers of our videos.

Let’s start with grabbing the viewing details for a video. In this case, I’ll use this Planets video that my daughter recorded for her class on astronomy:

<iframe src="https://embed.api.video/vod/vi16NDdXmGxk5QSggW54qw0v#autoplay#loop"  frameborder="0" scrolling="no" allowfullscreen=""></iframe>

The url for this video is: https://embed.api.video/vod/vi16NDdXmGxk5QSggW54qw0v

First I must [authenticate](https://api.video/blog/tutorials/authentication-tutorial/) myself at API.video, and I receive an access token that is good for an hour.

With the token, I can use the videoId to request all of the view information about my video with the [analytics API](https://docs.api.video/reference/api/Analytics).  The videoId for the video is the value at the end of the url (vi16NDdXmGxk5QSggW54qw0v):




In this case, I am requesting 25 results per page, and page one of the data.  That’s actually fine, since I know there are only 19 views on this video.  

The JSON result is pretty long, but here is what one entry looks like:


To me, this is super cool.  A person in Vietnam, using Firefox on Ubuntu, watched this video in June!  And there are 18 more of these to look at and to parse.

### Demo

We have created a demo that takes a videoId and counts the country, device and browser for each view, and places the results on a page. You can try it out at [whoswatched.a.video](https://whoswatched.a.video).

In order to look at the data, I am going to suck the JSON file into Couchbase - a database that uses JSON to create a "table" format similar to SQL. This will allow me to run queries on the JSON much like one would run a database query.

### Creating a database in Couchbase:

Download and install [Couchbase](https://www.couchbase.com/) on your computer.  When the install is complete, you’ll have an admin dashboard open in your browser (on my Mac it is running on localhost:8901).  We’d like to add in our api.video JSON file into a data bucket.  To create the bucket - navigate to the Bucket section and click the "ADD BUCKET" button. I have the memory set at the minimum 100 MB (there are all of 19 entries after all!).


Great - now we have our data bucket added.  Now we’ll want to import the JSON from api.video, so we can do our analysis.  This is done in the terminal using the ```cbimport``` command:

My username is Administrator with password 123456 (Google Chrome is mighty peeved about my use of an insecure password on localhost), adding a json file into the videoStats bucket.  Each video view has a sessionId, so I use that as a unique key.

I get a success message in my terminal, and looking back at the Couchbase admin panel under Documents, I can see each entry from the JSON has been added:


Now we must index the data. In the Query Editor, enter:

Now we can do data analysis of our video views. For example, to understand the number of views per country:

That’s pretty cool!  


## Live Stream Analytics

We can do exactly the same thing with live stream analytics. Note: these only show “views” of a live stream.  If you run a live stream and no one watches - there will be no analytics reported.  Further - if your live streams are saved as video on demand (VOD) for later use - any VOD analytics are saved with the newly created VOD video, and will have no connection to the original live stream.

Let’s look at a live stream that has a number of views.  On the [api.video](https://api.video) homepage, we have a demo that allows you to livestream right from the homepage.  The live streamer then “watches” their stream in the browser at the same time that they are broadcasting - guaranteeing that every live stream gets at least one viewer (in the same location as the live streamer!)

The API call is similar to that of the VOD request, I just use the 'live-streams' endpoint as opposed to the 'videos' endpoint I used above.

### GeoLocation  


The live stream demo is hosted in North America and in Europe, and we use geolocation to direct our users to the correct server. Let’s see how well our load balancers are doing. Traffic directed to North America is on the left, and European traffic is on the right:


It looks like our load balancing is doing a bang up job. :)


Combining the two sets of data (I just created a new bucket with all the data added) allows us to see that api.video’s home page has been live streaming all around the world:


### Devices & browsers

Most of the streams are from desktop machines. All 28 phone instances correspond directly to 28 Android devices.(This is due to a limitation in Safari that prevents the demo from working on any iOS device.)  Of our Android users, we see 25 using Chrome, 1 Samsung Internet, 1 Opera (and one hidden variant.)

Desktop users are mostly Windows and Mac (and pretty evenly distributed), but also a good number on Linux/Ubuntu).


## Conclusion


The video analytics offered by api.video allow you to better understand who is consuming your content. In this post, we've walked through the steps to extract the data using the Analytics API in JSON format, and then ingested the data into a database for fast and easy queries.  

We used this data to see how the live stream demo on the api.video home page was used in July 2020.

How are you using api.video's analytics? Drop us a note in the [community forum](https://community.api.video) with your use cases!

Analytics with api.video

When video meets data: Introducing Analytics at api.video for better video insights

screenshot-2020-08-13-at-13-01-16.png

screenshot-2020-08-13-at-13-12-54.jpg

screenshot-2020-08-13-at-13-14-20.png

screenshot-2020-08-13-at-13-16-21.png

Couchbase results in Google Sheets to create this chart.

screenshot-2020-08-13-at-13-17-03.jpg

screenshot-2020-08-13-at-13-33-04.png

screenshot-2020-08-13-at-13-33-10.png

screenshot-2020-08-13-at-13-33-15.png

Dynamic Metadata

Online video training is huge. There are many companies that offer video training courses where the course follows one video after another. The only way to continue in the course is to finish a video, and when the video is completed, the next video is unlocked. This ensures that the video course is taken in the order designed by the instructor, and that the students are not 'skipping' ahead through the coursework.


Other use cases for this might be a corporate training, where it is required that every employee watches each video in a series to be compliant with the policies of an organization (as a veteran of AT&T, I have taken months of this sort of training)

In this post, we'll walk through how you can build a video training app with api.video. 

## Connecting a session to a user

The first step in any training course will be to login your user. In the case of training a video, we'll skip a secure login form (it is just a demo!) and simply ask you to enter your name:

large_screenshot-2021-06-28-at-18-14-33.png

medium_screenshot-2021-06-28-at-18-14-33.png

small_screenshot-2021-06-28-at-18-14-33.png

thumbnail_screenshot-2021-06-28-at-18-14-33.png

screenshot-2021-06-28-at-18-14-33.png

When you submit this form, we'll search through the videos connected to the course (in this case, they are hardcoded in the app as an array:

```
var videolist = ['vi47Q8KHXLYyaOoX2Yoznxqh','vi6QvU9dhYCzW3BpPvPsZUa8','vi1DrBc0VkPfedcfTc21U1TP'];
var videoDurations= [91,321,333];
```

Note, we also hardcode the duration of the 3 videos (but in a more dynamic app, you can get the video duration from the [video status](https://docs.api.video/reference/api/Videos#retrieve-video-status-and-details) endpoint.

Now for each of these videos, I have created  dynamic metadata entry:


```
	"metadata": [
		{
			"key": "classUserName",
			"value": "__classUserName__"
		}
	],
```

when the value of a metadata entry has two underscores on either side of the value, any value can be applied to the metadata entry.  In this case, we'll apply the username as the value.  We can search for any video sessions that have the classUserName "Doug" for each of the videos in the training session. (in the code below, I am using the NodeJS client:

```
			currentPage = '1';
      pageSize = '25';
      var metadata = {'classUserName': userName};
      var params = { videoId, metadata, currentPage, pageSize};
      console.log("params",params);
      const result = client.rawStatistics.listVideoSessions(params);

```

This will result in the first 25 sessions where the variable userName (Doug) is saved as the classUsername metadata. (Of course, if you believe that your users might have more than 25 sessions per video, you can expand that number up to 100 - but for a training course, 25 viewing sessions per video per user is probably more than adequate).

The response from this will be every session that the user has had for the video.  For each of these sessions, we want to know if the video was watched all the way through.  We've [written up this analysis](https://api.video/blog/tutorials/video-event-analysis-using-api-video-sessions/) of session events. As soon as we discover a session that has watched the video, we stop looking through the sessions.  

## How many videos to unlock?

This approach will then be completed for each video in the series, until we reach a video that has not been watched.  This is done through the recursive function iterateVideos:

```

function iterateVideos(videolist, videoDurations, userName, videoCounter){
  return new Promise(function(resolve, reject){
      //soo take list of videos, and iterate until we know which video can be watched.
      console.log("testing video "+videoCounter);
      var videowatched  = videoWatched(videolist[videoCounter], videoDurations[videoCounter], userName);
      videowatched
      .then(function(passfail){
    
        console.log("video "+videoCounter+ " "+ passfail);
        if(passfail){
          //video was watched, so lets check the next one
          videoCounter++;
          if (videoCounter < videolist.length){
            var nextVideo = iterateVideos(videolist, videoDurations, userName, videoCounter);
            resolve(nextVideo);
          }else{
            //the last video was watched so, stop and show all the videos...
            resolve(videoCounter -1);
          }
        }else{
          //video was NOT watched start wit this video
          console.log("resolve the counter of the first video not watched", videoCounter);
          resolve(videoCounter);
        }
      }).catch((error) =>{
        reject(error);
    });



  });
```

The videoWatched function checks each session to see if the video has been completed.  

If the video has been completed, it returns true.  Then we check the next video to see if it has been watched. (If we reach the end of the video list - we show all of the videos.).

If the video has not been watched - we know where to stop displaying playable videos, and we can display the page.

### What the user sees

For this simple example with three videos, there are just three potential views:

* If no videos have been watched - the first video will have no sessions, and the session analysis will stop immediately. The page will show the first video as playable, and the subsequent videos as locked.

* If the first video has been completed, but not the second: the page will show the first two videos as playable, but the third video will still be locked.

* If videos 1-2 are completed (or if all 3 videos are completed), all three videos appear as watchable.


### Looking at the HTML

```
<iframe type="text/html" src="https://embed.api.video/vod/vi6QvU9dhYCzW3BpPvPsZUa8?metadata[classUserName]=Doug" width="960" height="320" frameborder="0" scrollling="no"></iframe>

```

See how each video adds the ```metadata[classUserName]=Doug```  this will ensure that any video session that is started on this page will be assigned to the user Doug. Once a video is watched, the user can refresh the page, and all the session data will be recalculated, and the next video will be unlocked.


## Build your own video training app

With api.video, you can easily upload your videos for playback. Using our analytics and dynamic metadata, we can build a training application that unlocks each video as content is viewed. Build your own based on our code on [Github](https://github.com/apivideo/trainingavideo). If you have question, feel free to reach [our community](https://community.api.video/) or [test it now](https://dashboard.api.video/register) in our free Sandbox environment.

Build a self guided training course with api.video

large_build-a-self-guided-training-course-with-api-video.png

medium_build-a-self-guided-training-course-with-api-video.png

small_build-a-self-guided-training-course-with-api-video.png

thumbnail_build-a-self-guided-training-course-with-api-video.png

build-a-self-guided-training-course-with-api-video.png

Video Sessions (Analytics)

How much of your video is being watched?  With api.video analytics, we can tell you exactly how much of the video was watched.  In this post, we'll walk through how to parse video session data in order to add up how much of the video was watched in a session.

## A video Session

A video session occurs when an api.video player is opened in a browser.  As long as the same window is used, each viewing of the video will be added to that one session.

You can get a list of your video sessions by using the [analytics endpoint](https://docs.api.video/analytics/overview) for a given videoId. In my code (using NodeJS), it looks something like this:

```
var params = { videoId, metadata, currentPage, pageSize};
  
const result = client.rawStatistics.listVideoSessions(params);
  result.then(function(videos) {
        var sessionList = videos.data;
        console.log("Number of sessions to test " , sessionList.length);

          for(i=0;i<sessionList.length;i++){
            //get each session ID, and figure out how long each session watched the video
            var sessionId = sessionList[i].session.sessionId;
            pageSize = '100';
            console.log(sessionId);

```


The Node endpoint takes my parameters (including the videoId I wish to analyze) and sends it to the ```client.rawStatistics.listVideoSessions``` endpoint.  This returns an array of the sessions that can be analyzed. 

The log will list a count of sessionIds, and then list each sessionId. Here is an example output from this code snippet:

```
Number of sessions to test  8
ps5orCkYsuaMw08btQmsW8vp
ps24iGEi011m9xKPqdTnIOvZ
ps7ODtZR04dfRBQCcarOIhv7
ps19mQmv5CTQwdeb75n8lLWr
ps1UdYeHbp6tQ21vrGUI8gXw
ps6xqBySKoSQfmG4zjcyZtWU
ps3cLLchT0Os75lzXovlCqTe
ps3MpNgw5Ax5EQ4GSAVyODRh
```

## get Session Events

In each session, the video player records each event, and sends it back to api.video.  Using the [Session event](https://docs.api.video/analytics/overview) API endpoint, we can retrieve each of these events.

```
 var sessionParams = {sessionId, currentPage, pageSize}; const sessionData = client.rawStatistics.listSessionEvents(sessionParams);
    sessionData.then( function(lastSessionData) {
      //this is the session data
      console.log("session events", lastSessionData);

```


The response of this endpoint looks something like this:

```
session events RawStatisticsListPlayerSessionEventsResponse {
  data: [
    PlayerSessionEvent {
      type: 'ready',
      emittedAt: 2021-06-17T19:00:54.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'play',
      emittedAt: 2021-06-17T19:00:55.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'end',
      emittedAt: 2021-06-17T19:02:27.000Z,
      at: 91,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'pause',
      emittedAt: 2021-06-18T10:59:03.000Z,
      at: 91,
      from: undefined,
      to: undefined
    }
  ],

```

In this case, the video is ready at time =0, begins playing, and then reaches the end at 91s.  The window is closed a day later, sending a pause event.  (this is just evidence that your author has a browser tab problem).

Using this data (and with the knowledge that the video is 91 seconds long), it's pretty easy to determine that the entire video was watched in this session.  from ready to the first pause is 91s, so the video must have been completed. But what about more complicated viewing patterns?  Let's look at an example:


```
  data: [
    PlayerSessionEvent {
      type: 'ready',
      emittedAt: 2021-06-21T12:33:06.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'play',
      emittedAt: 2021-06-21T12:36:13.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'pause',
      emittedAt: 2021-06-21T12:36:18.000Z,
      at: 81,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'resume',
      emittedAt: 2021-06-21T12:36:19.000Z,
      at: 81,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'seek.forward',
      emittedAt: 2021-06-21T12:36:19.000Z,
      at: undefined,
      from: 5,
      to: 81
    },
    PlayerSessionEvent {
      type: 'end',
      emittedAt: 2021-06-21T12:37:19.000Z,
      at: 91,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'pause',
      emittedAt: 2021-06-21T13:10:18.000Z,
      at: 91,
      from: undefined,
      to: undefined
    }
  ],
```


In this session, we again start playing at time = 0, but the next set of events occur at 81s (pause/resume). So the video stopped and restarted at t=81. The next event tells us how we got to t-81 - the view skipped ahead (noted as a 'seek.forward' event) at t=5, to t=81. The video paused because the video had to load, and then from t=81, it played until the end at t=91.  

In this case, even though the playback started at t=0, and ended at t-91, no one would consider this video fully watched, as the viewer skipped 76s of the video.

## Calculating the time watched

To calculate the time watched, we'll add up the time between every play/resume event and every pause/end event.  Then we'll subtract any time in a 'seek.forward' event.

```
 for(j=0; j< numberOfEvents; j++){
        if(lastSessionData.data[j].type == "play" || lastSessionData.data[j].type == "resume"){
          //start time measure
          starttime = lastSessionData.data[j].at;
          counting = true;
          console.log ("start" , starttime);
        }else if(lastSessionData.data[j].type == "pause" || lastSessionData.data[j].type == "end"){
          if(counting){
            endtime = lastSessionData.data[j].at;
            counting=false;
            console.log ("stop" , endtime);
            console.log ("added time" , endtime-starttime);
            summedtime += endtime-starttime;
            
          }
        }else if(lastSessionData.data[j].type == "seek.forward"){
          console.log("seeked forward", (lastSessionData.data[j].to - lastSessionData.data[j].from));
          summedtime -= (lastSessionData.data[j].to - lastSessionData.data[j].from);
          //if there was a seekforward, the max time previously calculated previously is no longer valid and needs to be recalculated.
          maxWatchedTime = 0;
        }
        console.log("summedtime: ", summedtime);
				
				
}

```

We can log the math that happens as we iterate through the events:

```
summedtime:  0
start 0
summedtime:  0
stop 81
added time 81
summedtime:  81
start 81
summedtime:  81
seeked forward 76
summedtime:  5
stop 91
added time 10
summedtime:  15

```

Comparing these events - we can see that from the first start to the first pause is 81seconds, but then we encounter the seeked forward of 76 seconds - leading to a summed time of 5 seconds.  After the last 10 seconds are watched, we have a total of 15 seconds of the 91 second video watched.


## Playback totals

When watching required training videos, it is often mandatory that the time watched is logged and and recorded. With the api.video session data, we can track each user's viewing to know if they have completed a video, or if they must re-watch the video.

In a future post, we will combine this video watching algorithm with code to 'unlock' subsequent videos in a training series.

Video event analysis using api.video sessions

large_screenshot-2021-06-21-at-13-06-24.png

medium_screenshot-2021-06-21-at-13-06-24.png

small_screenshot-2021-06-21-at-13-06-24.png

thumbnail_screenshot-2021-06-21-at-13-06-24.png

screenshot-2021-06-21-at-13-06-24.png

Erikka Innes

Python

thumbnail_videoanalyticsapivideo.png

large_discorddemoapivideo.png

medium_discorddemoapivideo.png

small_discorddemoapivideo.png

thumbnail_discorddemoapivideo.png

large_forwardseekapivideo.png

medium_forwardseekapivideo.png

small_forwardseekapivideo.png

thumbnail_forwardseekapivideo.png

large_cleanedupdata.png

medium_cleanedupdata.png

small_cleanedupdata.png

thumbnail_cleanedupdata.png

You can use api.video's analytics with Observable to create a lot of different charts. We've already made a [choropleth](https://api.video/blog/tutorials/use-observable-to-create-a-choropleth-map-of-your-viewers/), [a map that shows viewer density by marker size](https://api.video/blog/tutorials/api-video-analytics-add-markers-representing-viewer-density-per-city-to-a-map-wit/), and now today we'll create a pie chart.

## Prerequisites
For this tutorial, you'll need: 

* api.video account - sign up here
* Observable account - sign up here
* Python installed with requests, pandas, csv



large_apivideopiechartobservable.png

medium_apivideopiechartobservable.png

small_apivideopiechartobservable.png

thumbnail_apivideopiechartobservable.png

apivideopiechartobservable.png

## Retrieve Your Data
To retrieve your data, you're going to authenticate with your api.video API key. Then when you have the token, you retrieve all live streams, VODs and the sessions associated with them. Before going into the code sample, if you want you can check out the API reference documentation for live streams here: [Live streams](https://docs.api.video/reference/api/Live-Streams#list-all-live-streams)

## Create a DataFrame with Your CSV File
With this code snippet, we'll create a dataframe, and drop information down to only what we'll need for our pie chart. The other information was included for reference, and in case you want to do something else with this subset of data.


The code sample assumes your csv file is in the same folder as your code. 

Now we're ready to build our map in Observable.

## Configure Observable

In this section, we walk through how to get your pie chart set up on Observable. If you haven't done so, sign up for an Observable account. Then do the following:

1. Navigate to our Observable notebook [Pie Chart for api.video Analytics Data](https://observablehq.com/@erikkai/pie-chart-for-api-video-analytics-data).
2. Click the three dots in the upper right corner. A menu opens.
3. From the menu, choose **Fork**. Now you have your own copy of the map to edit and play around with.
4. Click the three dots in the upper right corner again and choose **File attachments**.
5. Add the csv file you made using the pandas code. 

Everything should work. You might find that the count for each operating system doesn't show, or the operating system name doesn't show if the pie slice would be too small. You can tweak the titles in the CSV to make them shorter, leave it, or you can try a [Donut Chart](https://observablehq.com/@erikkai/donut-chart) to see if that looks better. 

There's lots of things you can learn from your data. 

large_apivideodonutchartobservable.png

medium_apivideodonutchartobservable.png

small_apivideodonutchartobservable.png

thumbnail_apivideodonutchartobservable.png

apivideodonutchartobservable.png

## Analyzing Your Data
You can analyze your data many ways. For our example, because this is an api.video account, we might use this data a few different ways. We might assume that creating content suited to Mac and Linux is ideal, because half of our viewers are looking at demos from platforms that are Mac or Linux related. But, we might also make a choice to create more Windows focused content, because we have a lot of viewers from Windows operating systems. 

If we were building demos for mobile, this pie chart might indicate that Android demos would be more popular than iOS. 

Another way to interpret the data would be that we have less viewers from certain platforms because we don't target their use cases in our demos as much. With trial and error, we could use this data to make some educated guesses, tweak our content strategy and then come back and check the data. 

You could also combine this information with details about what country a viewer is from, and then figure out if certain regions have platform preferences. 

Have fun playing around with your data! 

Which operating system is most popular with api.video Analytics

api.video Analytics: Create a pie chart showing what operating system is most popular to view

large_api-video-blog-video-trends.png

medium_api-video-blog-video-trends.png

small_api-video-blog-video-trends.png

thumbnail_api-video-blog-video-trends.png

api-video-blog-video-trends.png

Video trends

Netflix, one of the world's biggest media services, is valued at a [whopping $125 billion](https://thesmallbusinessblog.net/netflix-net-worth/) and has a 93% retention rate with customers after they sign up. While there are many factors that contribute to this, like great content and an intuitive customer experience, a lot of Netflix's success also comes from its use of big data and analytics. With 151 million subscribers, and more added every day, they have a lot of information to work with. 

While you might not have 151 million subscribers for your content just yet, that doesn't mean you can't use some of the analytics techniques Netflix uses to keep viewers engaged and constantly watching. From years of experimenting, Netflix has a very sophisticated system. We'll stick to taking a look at some of the more obvious elements of their system that you could implement right away, such as: 
* User Input
* Tags
* Behavioral Data

## User Input 

One of the most obvious ways Netflix collects data about what viewers like, is by asking them. Netflix lets viewers directly list what they do and don't like with a **+** button that lets them add to My List - a list of content they want to watch. And it also lets them click a thumbs up icon for like and thumbs down for dislike. 

medium_netflixlikebuttonapivideo.jpg

small_netflixlikebuttonapivideo.jpg

thumbnail_netflixlikebuttonapivideo.jpg

netflixlikebuttonapivideo.jpg

In addition to these choices, when you first sign up, you can tell Netflix what kinds of shows you'd be interested to kickstart recommendations from Netflix. Surprisingly, this isn't the best way for Netflix to find out what people really want to watch. For example, according to a Wired article, Carlos Gomez-Uribe (previously Netflix's VP of Product Innovation: Personalization Algorithms)  [said](https://www.wired.com/2013/08/qq-netflix-algorithm/#:~:text=The%20company%20estimates%20that%2075,activity%20is%20driven%20by%20recommendation.&text=We%20spoke%20with%20Netflix's%20recommendation,they%20control%20what%20you%20watch.) "Many people tell us they watch foreign movies and documentaries, but in practice, that doesn't happen." While asking people about their interests is part of the puzzle, you shouldn't stop here - you'll need to look into viewers' actual habits on your platform.

## Create Tags for Show and Movie Characteristics 

Netflix uses very detailed tags to describe the content it provides audiences with. These help Netflix make better recommendations, and they help users when they use the search bar. The most obvious way information is categorized includes: 

* Titles - the title of the content, or part of a title
* Rating - how the content is rated, like PG or G
* People - who is in the movie, or involved with its creation
* Genres - a category characterized by form, style, and subject matter
* This show is - qualities the show has in terms of its style, tone, and voice

Something fascinating about Netflix's tagging is that, at least at one point, they divided their content into [76,897 micro-genres](https://www.theatlantic.com/technology/archive/2014/01/how-netflix-reverse-engineered-hollywood/282679/). Alexis Madrigal of The Atlantic scraped these and used them to create a new-genre generator. They also hand tag their content using their system. 

Maybe 76,897 micro-genres is a tad steep for your project, but you can still benefit from tagging your content so it's easier to search and build your own algorithms for. Create your own tagging system. api.video shows you the basics in [Video Tagging Best Practices](https://api.video/blog/tutorials/video-tagging-best-practices/). 

## Behavioral Data

When you watch content on Netflix, you don't always say what you liked or didn't like. You might not add anything to a list, or click a thumbs up button. But Netflix makes note of what you watched, and how fast you watched it. In a Wired article, [Tom Yellin, VP of Product Innovation at Netflix](https://www.wired.co.uk/article/how-do-netflixs-algorithms-work-machine-learning-helps-to-predict-what-viewers-will-like) stated: "We take all of these tags and the user behavior data and then we use very sophisticated machine learning algorithms that figure out what's most important - what should we weigh. How much should it matter if a consumer watched something yesterday? Should that count twice as much or ten times as much compared to what they watched a whole year ago? How about a month ago? How about if they watched ten minutes of content and aandoned it or tehy binged through it in two nights? How do we weight all that? That's where machine learning comes in."

Using api.video analytics, you're able to retrieve analytics per session. You can track sessions across content and player. You can see how long a session lasted, and how the viewer interacted with content while they were watching. You're also able to set up metadata to collect information in a session to find out what a viewer likes and doesn't like. Based on their choices, you can suggest other content they might like during their session. api.video provides a tutorial to get you started thinking about how to do this in our [Dynamic Metadata](https://api.video/blog/tutorials/dynamic-metadata/) tutorial. 

Viewer data is anonymized in sessions. If you wanted to connect it with someone's account to build out a recommendation system, you'd need to set up a log in mechanism, then connect their session details with their log in information and store it in a database for review. 


medium_netflixtagsapivideo.jpg

small_netflixtagsapivideo.jpg

thumbnail_netflixtagsapivideo.jpg

netflixtagsapivideo.jpg

## Conclusion

There are many subtleties to designing a recommendation system, but it all starts with the right metadata and analytics information. Offering detailed tags to categorize content, keeping track of how long and how fast viewers watch your content, learning what kinds of suggestions you should and shouldn't make, knowing what's popular in different areas, all of this and more goes into crafting the perfect system. If you want to get started experimenting with your own analytics data, check out some of api.video's content on the topic!

Video on demand

Live streaming

Analytics

Video infrastructure

Video player

AI features

See all features

Online learning & Corporate training

Social & Entertainment

Marketplace & E-commerce

Communication & UGC

Generative AI

Quickstart guides

Documentation

Ecosystem catalog

Clients & SDKs

Community

Blog

Demos

Customer success stories

Help center

Analytics