Analytics #

Retrieve analytics for your videos.

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'. For example dimension=day.

2. 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. For example metric=views.

3. You need to provide a start date. This must be passed in the standard YYYY-MM-DD format. All times are UTC. For example start=2022-01-01.

4. You need to provide an end date. This must be passed in the standard YYYY-MM-DD format. All times are UTC. For example end=2022-01-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=2022-01-01&end=2022-01-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 from a particular country like GB (not every country). This is what this filter parameter is for.

Each filter follows the format of: name:operator:value

The name is the field to test the value of. For example video_id

The operator will normally be 'eq' since you will want to match a value However you may need to use others:

And of course the value is what you are looking to match. For example to limit to the ID of a video, 'abcde12345abcde12345a' would be sent as:

?filter=video_id:eq:abcde12345abcde12345a

You can provide several within this filter parameter. Separate them with a semi-colon ; and that will combine them (an AND).

Note: You may need to URL-encode the value if it contains non-alphanumeric characters. Each language will have its own function to do that. For example PHP has urlencode. JavaScript has encodeURIComponent.

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 #

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=2022-01-01&end=2022-01-07"

Example response

{
  "success": true,
  "result": [
    {
      "day": "2022-01-01",
      "views": 123
    },
    {
      "day": "2022-01-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 - 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=2022-01-01&end=2022-01-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": []
}