Analytics API Migration: v0 to v1

This topic provides information for developers who are migrating apps and integrations from the v0 (Limited Availability) version of the Analytics API to version v1.

New features

v1 Enhancements

If you are currently using the Limited Availability version of the Analytics API, there are many reasons to upgrade your apps to the v1 version. Here are some of the enhancements offered in the v1 version:

  • Generate reports on multiple accounts: you can now generate reports on more than one account using the accounts parameter - see more...
  • Filter videos by video properties: you can now select the videos you want to report on using video properties such as tags, custom fields, and reference ids - see more...
  • Engagement endpoints: there are new engagement endpoints that allow you to get detailed engagement data for recent views - see more...

General changes

Base URL

The base URL for the API has changed:

Old URL:

https://data.brightcove.com/analytics-api/videocloud

New URL:

https://analytics.api.brightcove.com/v1

Authentication

Authentication via the v0 (Limited Availabilty) is no longer supported. You must get access tokens for the Analytics API via the Brightcove OAuth Service.

See Managing API Credentials for information on obtaining client credentials for the Analytics API.

In order to use the video property filters, your client credentials need to have permisssions for both:

  • video-cloud/analytics/read
  • video-cloud/video/read

Note: you can also use the OAuth service to authenticate calls to the v0 API. You may want to test this with working apps before migrating to v1, to make sure you have the authentication implemented correctly.

Rollups

Account rollup requests are no longer supported.

If you were using rollups to get detailed engagement information on recent video views, you will now be able to obtain these through the new engagement endpoints.

Report Changes

Reports

Reports are now accessed through the data resource rather than report:

Old report endpoint

https://data.brightcove.com/analytics-api/videocloud/accounts/{accountId}/report

New report endpoint

https://analytics.api.brightcove.com/v1/data

Accounts

For reports, accounts is now a parameter rather than a resource in the URL path - this allows generation of reports on multiple accounts:

Old way:

.../accounts/{accountId}/report...

New way:

.../data?accounts={account_id1},{account_id2}...

day becomes date dimension

The day dimension for reports is replaced by the date dimension. The date dimension works in the same way and returns the same data as the old day dimension.

For example:

/data?accounts={account_id1}&dimensions=date&from=2015-04-19&to=2015-04-20

See the guide to the date dimension for more information.

date_hour dimension

The date_hour dimension is used like the date dimension, but allows you to get hourly data for periods within the previous 32 days.

If the range for the date_hour requests extends outside the previous 32 days, an error will be returned. To specify hours of the day for request, set the from and to parameters to millisecond value of epoch time rather than using MM-DD-YYYY dates.

For example:

/data?accounts={account_id1}&dimensions=date_hour&from=1429450459000&to=1429536859000

See the guide to the date_hour dimension for more information.

Top-level fields for reports

Reports will always have these three top-level fields (only):

  • summary
  • item_count
  • items

Fields for reports on multiple dimensions

Fields returned for reports on multiple dimensions will be a union of the fields for each dimension included in the request.

See the Analytics API Overview for information on what dimensions can be combined in reports.

Strict validation on fields

The fields and sort parameters are strictly validated. If you include a field that is not supported for the call you are making, an error will be returned.

No fields=all

fields=all is no longer supported. The fields you want to return for items must be specified.

See Dimensions for the fields supported for each dimension.

video.reference_id and video.tags

If you include video.reference_id and/or video.tags in fields for reports on the video dimension, they will be returned in the response (or null if there is no reference id, an empty array if there are no tags).

Filtering by video properties

The where filter syntax for video properties is as follows: where=video.q=={property}:{value}. For example:

Filter by tags

where=video.q==tags:foo,bar

Filter by reference ids

where=video.q==reference_id:refid1,refid2

Remember that this data is cached for 24 hours, so will not reflect changes made in the past day. The analytics data is real-time - only the CMS data is cached!

More video properties

Some additional video properties you can filter on:

Property Description Example
name return videos with term in name video.q==name:birds
description return videos with term in description video.q==description:birds
custom_fields return videos with a custom field having that value video.q==custom_fields:nature
created_at return videos created in date range video.q==created_at:2015-01-01..2015-03-31
updated_at return videos last modified in date range video.q==updated:2015-01-01..2015-03-31

See the CMS API Search Videos Guide for available search parameters.

Engagement

Engagement endpoints

Three new engagement endpoints allow you to get granular engagement information for each 100th part of videos:

Account averages

.../engagement/accounts/{account_id}

Averages for a player

.../engagement/accounts/{account_id}/players/{player_id}

Engagement for a video

.../engagement/accounts/{account_id}/videos/{video_id}

The only parameters supported for engagement endpoints are from and to, and only periods within the previous 32 days are supported for engagement endpoints.