Overview: Analytics API v1

In this topic, you will get an overview of the Analytics API.
 

Introduction

The Analytics API allows you to obtain analytics data for your Video Cloud accounts directly. You can also view the built-in analytics reports in the Analytics Module of Video Cloud Studio. Accessing the data programmatically gives you additional flexibility.

Also see the API Reference.

Typical uses

Here are some typical uses of the API:

  • Creating custom charts and displays
  • Working with multiple APIs together - for example, getting video data using the CMS API for videos with the most views over the previous week
  • Combining your video analytic data with other site analytics data
  • For some sample solutions, see

Base URL

The base URL for the Analytics API is:

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

Headers

Authentication (required)

The Analytics API uses the Brightcove OAuth Service to authenticate calls.

You will first need to obtain client credentials (a client_id and client_secret). This is a one-time operation that can be performed using the OAuth Credentials UI. You can get client credentials directly from the Brightcove OAuth Service using CURL, Postman, or Insomnia.

You need both Analytics Read and Video Read permissions for client credentials:

Permissions for Credentials
Permissions for Analytics API Credentials

If you are creating your credentials directly through the OAuth API, the required permissions are:

  [
    "video-cloud/analytics/read"
    "video-cloud/video/read"
  ]

You will also need an access_token, which is obtained using the client_id and client_secret and passed in an Authorization header with your API request:

  Authorization: Bearer {access_token}

The access_token expires after five minutes, so you must obtain one for each request, or check to make sure that your token is still valid. See Getting Access Tokens for a detailed explanation of how to get access tokens, including code samples.

Accept-Encoding: gzip (optional)

Passing this header will cause the response to be returned in compressed form. This may improve performance for large reports.

Caching

For performance reasons, API responses are cached for approximately 5 minutes, though the exact amount of time may vary based on several factors. For any Analytics API query, you can get information about the cache from the response headers:

Cache Control Headers
Cache Control Headers

The Cache-Control tells you the maximum time the results will be cached for in seconds (in the example above, 24 seconds). The Last-Modified and Expires headers tell you when the current cache was created and when it will expire.

In most cases this is probably not an issue, but if the freshness of analytics data is of critical importance, you should know that the longer a query runs, the longer it will be cached, and reports that fetch realtime (unreconciled hourly) data only will not be cached as long as those that fetch reconciled data (only, or in addition to realtime data). Find a full explanation of realtime and reconciled data if you like; the short version is that the Analytics API relies on two data buckets:

  • realtime, or hourly unreconciled data, which is made available immediately and stored for 32 days
  • reconciled data, which is stored permanently; realtime data is reconciled to improve accuracy and stored in the reconciled data repository every 24 hours

You can limit the results to reconciled or realtime data using the reconciled parameter.

To minimize caching:

  • Use the reconciled=false parameter to limit results to realtime data
  • Use a small date range, and be sure that the entire range falls within the past 32 days

Timeouts

Analytics API requests timeout after 8 minutes if not completed. If you see timeouts at less than 8 minutes, then the cause is some client-side limit.

Maximum items you can return

The maximum number of items that can be returned is one million. In most cases you are unlikely to hit the limit, but if you are requesting reports on the date dimension over a large span of time, for instance, it is possible. If you hit the million item limit, you will need to modify the request to reduce the number of items returned. Generally, the most straightforward way to do this will be to reduce the data range (using the from and to parameters discussed later).

Concurrent Requests

A single account is limited to one request at a time. Multiple concurrent requests will execute in series.

For example:

  1. Start an API request "A".
  2. Start API request "B" for the same account.
  3. Request "B" will not complete until "A" completes.
  4. If request "A" takes too long, request "A" will receive an error saying "your request is pending; try again".
  5. If request "A" takes too long, it may cause request "B" to receive the same error. Note that request "B" will get an error if the time to complete A + B is greater than our timeout value.

If you make multiple concurrent requests, they will be processed one at a time, in the order received.

Requests that return with a "pending error" will eventually complete and be saved to our cache. This means that future requests for the same data will return almost instantly, but only if the request is made before the five minute cache expires.

Your systems should handle the pending error by waiting 2-4 minutes and making the same request again.

Best practices

Request types

The Analytics API accepts three request types

Data (also called a Report)
A report on one or more dimensions. The endpoint for a report request is: 
  https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions}
Engagement report
Detailed engagement data that is available for periods within the past 32 days. See the engagement section for more details.
Video information endpoint
A specific piece of analytics data served with minimal latency. See Video Data Endpoint for more information.

Where filters and date ranges can be applied to reports. Report requests can have additional parameters detailed in this document.

Dimensions and fields

Detailed information on dimensions and fields is now in a separate document: Overview of Dimensions, Fields, and Parameters.

Parameters

Detailed information on parameters is now in a separate document: Overview of Dimensions, Fields, and Parameters.

Engagement reports

Detailed engagement reports showing views for each 100th part of videos (or the averages across all videos for an account or player) are available for periods within the past 32 days. (Requests for date ranges outside the past 32 days will return an error.)

Account engagement

To get average values for engagement on viewed videos, use the endpoint:

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id

Player engagement

To get average values for all videos viewed in a player, use the endpoint:

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id

Video engagement

To get engagement data for a specific video, use the endpoint:

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id

Live Analytics

The Analytics API provides two endpoints for retrieving analytics for Brightcove Live streams, either by a time series or by event. See the Analytics API Reference for details.