Tips for working with api.video analytics data

You may want to grab analytics data from api.video and then visualize it different ways. Today we'll take a look at the data you can use, what that data looks like, and the code snippets for data retrieval. api.video has three sets of analytics you can collect:

• Video on Demand Session Analytics
• Live Stream Session Analytics
• Player Session Analytics

Everything is set up so you can pull details at a granular level - so for each request to the API, you would choose the video, live stream, or player you want details about, and send an individual request for information about that that asset. If you want to pull data for an individual asset, or multiple assets, the first thing you need to do is get a list of those assets.

You can also see a fun project using api.video analytics data over at Observable. We made a notebook that shows where all our live stream viewers watch from.

Get All Videos, Live Streams, or Players

The first step in using your analytics data, is to find out what you have available to analyze. You're going to want to know what videos, live streams, and players you have.

1. Authenticate with your API key and get a token.
2. Use the token with the List all videos, List all live streams, or List all players endpoint to get all listings for everything in that category.

The code for this part looks like this:

In this sample, we went through every endpoint and got a complete list of assets. Then, so we don't have to keep going back to the API for this information, we output each set of details to a .json file. You probably won't want to necessarily save this, but for learning or browsing, it's great to be able to open the file and see this data you'll be working with. If you want to experiment with retrieving data from these files and converting to different formats, these can be helpful.

Data Structure for a Live Stream

If you were to retrieve a single live stream, it would contain the data shown here, and a pagination section in case you have so many entries you need to retrieve multiple pages of asset listings.

Data Structure for a Video

As with live streams, if you were to retrieve a single video, it would contain the data shown here. Notice there's a ton of videos - 608 to be exact, and the pagination section provides details for grabbing additional pages of data so you can get an exhaustive list of all assets if you need it.

Data Structure for a Player

For players you get details about how each one is customized. It has the same pagination feature as the other data structures. Because you don't use this information to retrieve session details, it's more for informational purposes only if you wanted to know about the players you have.

Retrieve Sessions

The next part of retrieving your data is to grab session information. Because the analytics endpoints are set up to be granular, you need the unique live stream, video, or player ID to use with the associated endpoint. Then you can retrieve details about all sessions for that endpoint. Live stream and video sessions come back using the same structure. Players are different (as you'll see).

The code to retrieve details about one asset for video or live stream would be:

Data Structure for Live Stream and Video

Live streams and videos bring back information with the same format. Something to remember is when the information comes back, it will not include the title of your live stream or video, or its type. If you were to get back one single session for a live stream or video, it would come back like this:

Data Structure for Player

Because you are reviewing session details on a player for a particular video or live stream, you may want to note this in your data at some point. The returned data for a session doesn't include details about what video or live stream it's for beyond repeating the session ID in the pagination URLs.

Tips for Handling Data

This section includes some tips for handling your analytics data.

• It will be easier if you know what you want to do at the start so you can retrieve appropriate information for your project.
• When creating a file to work with, remember that flattening the JSON makes your project easier. Flattening the JSON means that you undo the nesting for each entry, so that everything for each is in a single row.
• You may want to add extra details when you retrieve informat for an asset, like a column for the title. If you mix your live stream and video data to get big picture analytics data, you may want to have another column that lists whether something is a live stream or video. Otherwise, you don't have a way to retrieve that information later.
• If you don't know what you want to do, you may want to design a way to gather all the data together. One way is to put live stream and video data into a table, and then join that table to a player table based on session ID. This would be a way to build a master file of your data.