Analytics

Analytics

Retrieve analytics for your videos by making the following request:

RequestDescription
GET /analyticsReturns a report based on the options passed in the query string

GET /analytics

Each request has four required parameters:

  1. You need to provide a dimension. You can think of this as like the x-axis on a graph. It is the 'bucket' your data falls into. Often it will be a time, like 'day' (meaning your report would show views per day). However you can also pass values such as 'domain' or 'country'.

dimension=day

  1. You need to provide a metric. You can think of this as like the y-axis on a graph. For now the only value supported is views.

metric=views

  1. You need to provide a start date. This must be passed in the standard YYYY-MM-DD format. All times are UTC.

start=2021-02-01

  1. You need to provide an end date. This must be passed in the standard YYYY-MM-DD format. All times are UTC.

end=2021-02-07

Combining all of the above, at this point your URL will look like this:

https://api.vidbeo.com/v2/analytics/videos?dimension=day&metric=views&start=2021-02-01&end=2021-02-07

You may then like to provide a combination of the following optional parameters:

a) filter

You can restrict the data returned by providing a custom filter. For example you may only want to see the data for a particular video ID (not all of them). Or you may only be interested in viewers in the UK (not every country). Or who watched a video on example.com (not every domain). This is what this filter parameter is for.

Each filter follows the format of: nameoperatorvalue

The name is the column to test the value of. For example, 'video_id'

The operator will normally be '==' since you will want to match a country, ID, domain ... However you may need to use others:

OperatorDescription
==Equals
!=Does not equal
>Greater than
<Less than
>=Greater/equal
<=Less than/equal
=@Contains string
!@Doesn't contain string

And of course the value is what you are looking to match. For example the ID of a video, 'abcde12345abcde12345a'.

For more complicated queries you can provide multiple ones within the same filter parameter. Separate them with a comma , for an OR or with a semi-colon ; for an AND.

Finally you need to URL-encode the values before sending them. Each language will have its own function to do that. For example PHP has urlencode. JavaScript has encodeURIComponent.

So let's say you only wanted to see data about views from the UK. We use the ISO-3166-1 two-letter country code to represent each for consistency, so you would be wanting country equals GB. So that would be country==GB. But we URL-encode it. So that would make your final filter parameter:

filter=country%3D%3DGB

b) by

You can choose how the returned results are ordered, or manage it yourself client-side. If you would like to specify a preferred option, you can provide this 'by' parameter. Since we return two values, a dimension, such as 'day', and a metric, such as 'views', you need to use one of those two. Here we've opted to sort by the number of views.

by=views

c) limit

To limit the number of results returned, you may want to add a limit value. This is used if you are only interested in seeing the top X (such as 10) results. We recommend using this to keep the response small. For example:

limit=10

Response format

KeyTypeDescription
analyticsArrayThe generated report as an array of objects, with each object usually having a pair of values (the dimension and metric)

The example requests below should hopefully make it clear how it all works, but, as usual, if you have any questions please get in touch.

Q: Show me the views per day, between 1st February 2021 and 7th February 2021

Here the dimension is day. So your request would be:

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/analytics?type=videos&dimension=day&metric=views&start=2021-02-01&end=2021-02-07"

Example response

{
"success": true,
"result": [
{
"day": "2021-02-01",
"views": 123
},
{
"day": "2021-02-05",
"views": 456
}
],
"links": {},
"errors": []
}

Each object in the returned array is one day's data. Each object contains the metric (the number of views/played events) along with the dimension (the day). In our example you will see that not all dates within the chosen range are present. A missing date means there were no recorded views. Over larger date ranges that makes the response size much smaller.

Q: Show me the top 5 domains my videos were watched on, between 1st February 2021 and 7th February 2021

As part of our analytics, we log the domain name the video was watched on (if known, as some browsers do not send this). For example www.example.com. Since videos may be embedded on many sites, it can be useful to see which sites your videos are most often viewed on.

Here we will make use of the by and limit parameters. The by to order by the "views". And the limit as 5 because we are only interested in the top 5 results.

curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/analytics/videos?dimension=domain&metric=views&start=2021-02-01&end=2021-02-07&by=views&limit=5"

Example response

{
"success": true,
"result": [
{
"domain": "example.com",
"views": 789
},
{
"domain": "www.company.com",
"views": 456
},
{
"domain": "unknown",
"views": 123
}
],
"links": {},
"errors": []
}

On this page