FAQ: Analytics API

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.

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:

1. The data is less than 3 days old. Analytics data less than 3 days old is provisional and subject to change at any time.
2. 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.

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:

1. 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.
2. 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.

The /data endpoint is currently cached for 3-4 hours between queries, so for lists of videos with traffic in the last hour, 3-4 hours intervals is the slightest delay that will give you a delta to work from.

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

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

Set the limit parameter for the Report equal to all.

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.

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

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.

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.

Analytics API sorts by video_view by default unless specific sorting is specified in the API call. In either case, if we have multiple values for given data points (exact video_view count for more than one combination), Analytics API doesn’t guarantee uniqueness, and pagination calls may return the same data in subsequent calls. API call with "limit=all" will provide exact info without any duplication. However, this can be an expensive call in terms of response time.

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.

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.