I’ve used this video of Tuba players playing the Beatles in other tutorial posts. So, we know it will have a lot of views. But, how many? Using the List Video sessions endpoint, we can get information about each time this video was played with the api.video player.
To use this API, you need 2 items: a videoId of the video you want to measure, and an authentication token. In order to authenticate your session, you need your api.video token. Read the details in the authentication tutorial, and then come back with your token (it will be valid for one hour).
In this example, we’ll use curl to access the video session endpoint. The videoId is vi4blUQJFrYWbaG44NChkH27. The curl request looks like:
curl --request GET \
--url 'https://ws.api.video/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=5&pageSize=100' --header 'authorization: Bearer {token}' --header 'accept: application/vnd.api.video+json'
I am requesting page 5 (currentPage in the url), with pageSize=100 (100 sessions per page, since I knew that this video had between 400 and 500 views. For simplicity, I’ll show just the 2 most recent sessions:
{
"data": [
{
"session": {
"sessionId": "ps4mPLq8bZzjXlxwJG4cg4vl",
"loadedAt": "2020-10-12T11:21:09+00:00",
"endedAt": "2020-10-12T11:27:20+00:00"
},
"location": {
"country": "United Kingdom",
"city": "Glasgow"
},
"referrer": {
"url": null,
"medium": "unknown",
"source": "unknown",
"searchTerm": "unknown"
},
"device": {
"type": "computer",
"vendor": "unknown",
"model": "Other"
},
"os": {
"name": "Mac OS X",
"shortname": "Mac OS X",
"version": "10.15.6"
},
"client": {
"type": "unknown",
"name": "Chrome",
"version": "85.0.4183"
}
},
{
"session": {
"sessionId": "ps42gcSLNv8hSQxKOWWgxeNj",
"loadedAt": "2020-10-12T11:43:56+00:00",
"endedAt": "2020-10-12T11:44:19+00:00"
},
"location": {
"country": "Netherlands",
"city": "Uithoorn"
},
"referrer": {
"url": "https://t.co",
"medium": "social",
"source": "Twitter",
"searchTerm": "unknown"
},
"device": {
"type": "computer",
"vendor": "unknown",
"model": "Other"
},
"os": {
"name": "Mac OS X",
"shortname": "Mac OS X",
"version": "10.15.7"
},
"client": {
"type": "unknown",
"name": "Safari",
"version": "14.0"
}
}
],
"pagination": {
"currentPage": 5,
"currentPageItems": 22,
"pageSize": 100,
"pagesTotal": 5,
"itemsTotal": 422,
"links": [
{
"rel": "self",
"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=5&pageSize=100"
},
{
"rel": "first",
"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=1&pageSize=100"
},
{
"rel": "previous",
"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=4&pageSize=100"
},
{
"rel": "last",
"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=5&pageSize=100"
}
]
}
}
Let’s start with the information at the bottom. We can get links for each page of sessions, and itemsTotal is 422 - meaning there have been 422 sessions watching this video.
Let’s look at the 2 sessions in the logs. The first session has sessionId = ps4mPLq8bZzjXlxwJG4cg4vl. This user watched the video for about 6 minutes based on the session length:
"loadedAt": "2020-10-12T11:21:09+00:00",
"endedAt": "2020-10-12T11:27:20+00:00"
We also know that they are in Glasgow, UK, using Chrome 85 on a Mac.. It just so happens that my ISP enters the internet in Scotland (all my advertising is Scotland based) even though my physical location is England, so this session is from my computer.
The 2nd session is interesting:
"location": {
"country": "Netherlands",
"city": "Uithoorn"
},
"referrer": {
"url": "https://t.co",
"medium": "social",
"source": "Twitter",
"searchTerm": "unknown"
},
I accidentally tweeted the url to this video, and deleted the tweet within 30 seconds, Yet, someone on Twitter in the Netherlands still got to see the video before the tweet disappeared.
Did you know that the api.video player works in Twitter? Now you do! Your analytics will show video plays from any share on Twitter!
Applications
With this data - you could build a map of where the video is being watched by country, and in some cases by city (with the caeat that this is not 100% accurate - my ISP says I am in Scotland). You can also understand the referring urls: Twitter, blogs, Linkedin, etc. Finally, you can also monitor the traffic patterns by day of week, time of day, etc.
Going even deeper
It is great to know that there was a video view at 11:21 GMT - but we can learn even more about this video view. Using the session events endpoint and the sessionId, we can actually describe the exact usage of that session. Making a request using a sessionId (note this is a different - more interesting - session):
--request GET \
--url 'https://ws.api.video/analytics/sessions/ps42gcSLNv8hSQxKOWWgxeNj/events?currentPage=1&pageSize=100' --header 'accept: application/vnd.api.video+json' --header 'authorization: Bearer {token}' --header 'accept: application/vnd.api.video+json'
This request will return all of the video player events in that session: so we can see any play, pause or seek events that occurred in playback:
{
"data": [
{
"type": "ready",
"emittedAt": "2020-10-11T20:43:32+00:00",
"at": 0
},
{
"type": "play",
"emittedAt": "2020-10-11T20:43:32+00:00",
"at": 0
},
{
"type": "pause",
"emittedAt": "2020-10-11T20:43:57+00:00",
"at": 2
},
{
"type": "resume",
"emittedAt": "2020-10-11T20:44:00+00:00",
"at": 18
},
{
"type": "seek.forward",
"emittedAt": "2020-10-11T20:44:00+00:00",
"from": 2,
"to": 18
},
{
"type": "pause",
"emittedAt": "2020-10-11T20:44:01+00:00",
"at": 19
},
{
"type": "resume",
"emittedAt": "2020-10-11T20:44:04+00:00",
"at": 2
},
{
"type": "seek.backward",
"emittedAt": "2020-10-11T20:44:04+00:00",
"from": 19,
"to": 2
},
{
"type": "pause",
"emittedAt": "2020-10-11T20:44:11+00:00",
"at": 9
}
],
"pagination": {
"currentPage": 1,
"currentPageItems": 9,
"pageSize": 100,
"pagesTotal": 1,
"itemsTotal": 9,
"links": [
{
"rel": "self",
"uri": "/analytics/sessions/psyd0zH6RWUCxP7xnWqcnKm/events?currentPage=1&pageSize=100"
},
{
"rel": "first",
"uri": "/analytics/sessions/psyd0zH6RWUCxP7xnWqcnKm/events?currentPage=1&pageSize=100"
},
{
"rel": "last",
"uri": "/analytics/sessions/psyd0zH6RWUCxP7xnWqcnKm/events?currentPage=1&pageSize=100"
}
]
}
}
The video was ready to play (entry 0) and started to play (entry 1) at 2020-10-11T20:43:32+00:00. (That is expected, as the player associated with this video is set to autoplay as soon as it is ready). The video is also set to loop, which is evident in the next entry.
The third entry shows that the video was paused at 2020-10-11T20:43:57+00:00. The video timestamp shows “2” meaning 2 seconds into the video. About 25 seconds elapsed since the video started, so how does that work? The video is about 20 seconds long, meaning that the video played to the end and started again before the pause occurred.
The next entries show that there is a seek.forward event from 2->18s, and the video resumed for one second before rewinding back to 2 and then playing to 9 seconds into the video.
Aggregating these session stats across all sessions can give you an idea of when users rewind - perhaps when an important point is raised - indicating that in future videos that data should be highlighted for your users. You can also see if there is early abandonment, or jumps ahead - as users look for the content that they are interested in.
Fast analytics
These results are available as soon as the session is completed. To see how quickly, I recorded a video where I watched the video, and then retrieved the analytics immediately afterward.
