FAQ: Analytics API

Below are some frequently asked questions about the Analytics API. For answers to some of the common questions about the Video Cloud Studio Analytics module, see FAQ: Analytics Module.

Date ranges

How do I return data for all time in a Report?

Set from=alltime in the request. You can also set to=now, but this isn't necessary, since now is the default value. Note: alltime does not work for a Rollup - instead you will need to set from to a date far enough in the past.

How do I get data for a specific day?

Set both the from and to values to that date. For example: from=2013-05-12&to=2013-05-12. In addition, you can query by the date dimension, which can be combined with other dimensions.

Should the Analytics module and the Analytics API give me idential data for the same date range?

Yes, but they may be different if you are comparing data that is relatively recent, and you obtain data from Studio and the API at different times:

The data is less than 3 days old. Analytics data less than 3 days old is provisional and subject to change at any time.
Data for same period is looked at when it was less than 32 days old, and again after it is 32 days old. After 32 days, data is moved to a separate "historical" repository, and at that point we discard some data, especially detailed engagement data. This means calculated fields such as engagement score may change slightly, because the calculation is being made on less granular data.

Data granularity

What is the granularity of recent Analytics data?

For the most recent 32 days (including the current day), the Analytics API reports an hour granularity, because it saves values into hourly buckets. However, the current hour is still being filled, so this can give the API the appearance of having more granularity than an hour when you ask for data that falls in the current hour.

For example:

If you ask for data from 3 hours ago for 9:15 and 9:20 you may get the same value if they fall in the same hour bucket; however, they may be different because all analytics data is provisional and subject to change until it is reconciled.
If you ask for data from 10 minutes ago, and then wait 5 minutes and ask again you may get a different value even if it is in the same bucket, because that bucket is still being updated.

What is the refresh interval for the analytics data?

The /data endpoint is currently cached for 5 minutes between queries, so for lists of videos with traffic in the last hour, 5 minute intervals is the smallest delay that will give you a delta to work from.

What is the granularity of historical Analytics data?

For dates earlier than the last 32 days, the Analytics API reports full day values. This means that if your requested from=1368334306919&to=1378446336919 (from Sun, 12 May 2013 04:51:46 GMT to Fri, 06 Sep 2013 05:45:36 GMT), you would get the same results that you would if you had requested from=2013-05-12&to=2013-09-06

Items and fields

What is the best way to tell how many stream starts there were in a period for one or more videos?

Just look at the video_view metric - this will always be equal to the stream starts. You can see this metric in all reports, and the summary will show you stream starts for all videos in the date range queried. To see stream starts for all videos in your account, you would just run this request:

    https://analytics.api.brightcove.com/v1/data?accounts={account_ids}&dimensions=video&limit=all&offset=0&fields=all

How do I return all items in a Report?

Set the limit parameter for the Report equal to all.

What data fields are returned for items by default?

By default, only video_view and the field corresponding to the dimension requested (e.g. destination_domain) are returned. To get additional fields, set fields=field_name1,field_name2 to return selected fields.

What does it mean if a field value is null?

A null value for a data field indicates that the data requested has not been processed. The most likely reasons are that:

The data you requested is very recent and has not been processed yet
The data you requested is very old and has not yet been imported into the current analytics system

I changed the name of one of my videos - why do I see the old name in Analytics data?

The new name will be recorded for any new analytics events, but we do not change the name in historical data - the video name returned will be the name it had at the time it was viewed.

Why don't I always see integers for engagement values?

It is possible for engagement numbers to return with decimal points. The reason is because engagement is normalized which means that it's a ratio of "video_percent_viewed * (video_engagement_25 / video_engagement_sum)" so based on the time range selected for the query you may see floating point numbers in cases where they don’t divide exactly.

How do I filter results by player?

Reporting

Why do I see 0 GB when I look at bandwidth used by a player?: In the past Brightcove has reported bandwidth by player, and so for customers that wanted to break things down by player they could use these metrics as a means of allocating bandwidth costs. However, as we move toward more manifest-driven delivery (HLS today and DASH in the future), the nature of segmented video will make tracking bandwidth by player inaccurate. Therefore, we will be deprecating the bandwidth by player dimension in the Utilization report. So going forward we recommend using seconds viewed by player in the Performance report to allocate costs by player.

Miscellaneous

Can I exclude employee views from analytics reports?: There is no easy way to do this, and for high-traffic videos, employee views are probably such a small percentage that their effect on analytics is negligible. However, for low traffic videos where you think it's important to do this, the simplest solution is to duplicate your production player(s) and have employees test/view videos on the copies. You can then use filters to create reports on your production player(s) only, using either the Custom Reports feature in the Analytics module or the Analytics API.