Date ranges
How do I get data for a specific day?
Set both thefrom
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 identical 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 requestedfrom=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 thevideo_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 thelimit
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