Overview: Analytics API v1

Product(s)
Video Cloud
Role(s)
API Developer
Topic(s)
Analytics
API Overviews
API(s)
Analytics API
Type
Support Doc

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:

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 or Postman.

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

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 below.

Accounts

The Video Cloud account(s) that you want a report for are specified using the accounts parameter. For example:

https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}

Dimensions and fields

Dimensions are the primary data buckets for analytics. To see full guides to the individual dimensions, click on the dimension name in the list below.

 
 

Select dimension(s) below to see the fields that can be returned for it. You can also click the Make a Request button to make a sample request and see the results. If you select multiple incompatible dimensions, you will see a message to that effect.

Input
Select Dimension(s) to report on:
 
 
Fields to return:
 
 

(uses a sample Brightcove account)

Output
Earliest from date for this dimension combination:  
 
Sample API request:
Response data
Response will appear here...

Notes

  1. By default, video_view is the only field returned - other fields will be returned only if they are specified in the value of the fields parameter.
  2. If you specify a field to return that is not supported for the dimension or dimension combination, an UNSUPPORTED_FIELD_COMBINATION_ERROR error will be returned.
  3. The bytes_delivered field includes all data delivered by Video Cloud to clients, including video data, images, text tracks and other assets, as well as the player code itself. Some of this data is obtained from CDNs, and may not be available for up to 3 days.
  4. In addition to the fields shown for the video dimension, you can also return video.custom_fields.{field_name}

Example request

A typical use case for getting a report on multiple dimensions: you want a breakdown of video views between desktop and mobile devices, and also want to know how many of the mobile device views were on iOS versus Android devices, and how many of the desktop views were on Macs versus Windows machines. Currently there is no standard report in the Studio Analytics Module that provides this information, but you can obtain it via this Analytics API call:

https://analytics.api.brightcove.com/v1/data?accounts=57838016001&dimensions=video,device_type,device_os&from=2014-01-01&to=2014-04-01&fields=video_view

(In this case we are requesting video views for the period from January 1 to April 1 in 2014.)

Example using cURL

If you want to try out the API using cURL, here are a couple of notes:

  • You will first need to get an access token
  • Since the URL for the request will always include URL parameters, you will need to enclose it in quotation marks (single or double)

Sample

Here is a sample cURL command:

curl -s --header "Authorization: Bearer $ACCESS_TOKEN" \
"https://analytics.api.brightcove.com/v1/data?accounts=$ACCOUNT_ID&dimensions=video&from=2017-04-04&limit=100"

Supported dimension combinations

For quick reference, the table below shows dimension combinations that are supported or not. Note that there are a few cases where more than two dimensions can be used. You can figure these out using the Dimensions and Fields tool above.

Supported Dimension Combinations
  account browser_type city country date date_hour destination_domain destination_path device_os device_manufacturer device_type live_stream player referrer_domain region search_terms social_platform source_type video
account n/a Yes Yes Yes     Yes Yes Yes Yes Yes   Yes Yes Yes Yes   Yes Yes
browser_type Yes n/a                                  
city Yes   n/a Yes                     Yes        
country Yes   Yes n/a         Yes   Yes   Yes           Yes
date         n/a                            
date_hour           n/a                          
destination_domain Yes           n/a           Yes           Yes
destination_path Yes             n/a                      
device_os Yes     Yes         n/a       Yes   Yes       Yes
device_manufacturer Yes                 n/a                  
device_type Yes     Yes             n/a   Yes   Yes       Yes
live_stream                       n/a              
player Yes     Yes     Yes   Yes   Yes   n/a Yes       Yes Yes
referrer_domain Yes                       Yes n/a   Yes   Yes Yes
region Yes   Yes Yes         Yes   Yes       n/a        
search_terms Yes                         Yes   n/a   Yes  
social_platform                                 n/a   Yes
source_type Yes                       Yes Yes   Yes   n/a Yes
video Yes     Yes     Yes   Yes   Yes   Yes Yes     Yes Yes n/a

Parameters

Below is a table summarizing the parameters available in the Analytics API. The use of the parameters is discussed in more detail in the sections that follow.

Parameter Required Description Values Default

Where filters

The general syntax for filters is:

where=dimension1==value1;dimension2==value2

For example:

https://analytics.api.brightcove.com/v1?accounts=account_id(s)&dimensions=device_type&where=video==video_id;device_type==tablet

Commas are treated as logical ORs, and semicolons as logical ANDs. For example, where=video==1234,5678;player==9876 is interpreted as "where video = 1234 OR 5678 AND player = 9876"

Spaces and special characters

String values should be URI encoded. You can also escape special characters using a "":

where=search_terms==boston,%20ma

You can use any dimension as a filter.

Filtering by video properties

Using the special where=video.q=={property}:{value} filter, you can limit your report to a specific set of videos based on a variety of properties, including:

  • tags
  • reference_id
  • custom_fields [1]
  • {a_specific_custom_field}
  • created_at

Notes

[1] The basic syntax is where=video.q==custom_fields:value (matches the value in any custom field) or where=video.q==myfield:value (matches the value in the specific custom field myfield). If you are searching on a specific custom fields, note that you must search on the Internal Name, not the Display Name:

Internal Name vs Display Name
Internal Name vs Display Name

One quick check on whether you are using the right name: the internal name will be all lowercase and contain no spaces.

Examples

Here are some example where filters for searching on tags and custom fields:

Single tag
where=video.q==tags:foo
Multiple tags:
where=video.q==tags:foo,bar
Custom fields
where=video.q==custom_fields:foo
Tags and custom fields
where=video.q==tags:foo,bar+custom_fields:fish

For a complete explanation of this query syntax, see Using the CMS API: Search for Videos.

Summary of filters and allowable values

    The following table shows allowable values for each dimension used as a filter:

    Dimension Filter Allowable Values

    Date ranges

    Date ranges, specified in from and to parameters for all types of reports, can be indicated in different formats:

    • Text values:
      • from=alltime
      • to=now (available and the default value for all requests)
    • Epoch time values in milliseconds, such as 1377047323000
    • Dates expressed in ISO 8601 standard international date format: YYYY-MM-DDformat, such as 2013-09-12. For dates expressed in this format:
      • Any date range specified will be interpreted in the timezone set for the account
      • The time for the date give will be interpreted as midnight ( 00:00:00) on the date specified in the timezone set for the account
    • Relative dates: you can express either of the to and from values relative to the other one in d (days) or h (hours). For example:
      • from=2015-01-01&to=31d
      • from=-48h&to=now
      • from=-2d&to=now (will give the same results as the previous example)
      • from=-365d&to=2014-12-31

      Note that negative numbers (-2d) are interpreted as "before" (the other value) and positive numbers (48h) are treated as "from" (the other value)

    To generate a report on some dimension like "video" for a single day, set the to and from values to that date:

    ...&dimensions=video&from=2013-11-01&to=2013-11-01

    Limit and offset

    The limit is the number of items to return (default: 10). To return all items, use limit=all. offset is the number of items to skip (default: 0). You can use limit and offset together to create an app that pages through the results.

    Reconciled data

    The reconciled parameter is a boolean. If it is set to true, the results will be limited to reconciled data. If false, results will be limited to realtime (hourly unreconciled) data.

    Geographical reports

    Dimensions for geographical analytics

    • country - As the ISO-3611-1 country code. eg: 'US'
    • region - As the ISO-3611-2 region code. eg: 'US-WA'
    • city - City name. eg: Seattle

    Note: For unknown country or region the API returns "ZZ" as the code (As per ISO-3611-alpha2).

    Fields and Sorting

    Use the fields parameter to specify the fields you want to return. By default, video_view is returned and the field corresponding to the dimension you are reporting on (e.g. destination_domain) are returned. See dimensions and fields for more details.

    Use the sort parameter to specify which metric field is used to sort the returned items; for example: sort=video_view. You can reverse the sort order by negating the sort field: sort= -video_view

    Calculated fields

    You can add calculated fields to your API requests using the syntax:

    fields=calulated_field_name:expression

    You can use calculated fields to create your own custom fields out of existing metrics, or to rename an existing field.

    The name for the calculated field can be any URI-compatible string. The expression can include regular field names and the following arithmetic operators:

    • + (addition)
    • - (subtraction)
    • * (multiplication)
    • / (division)
    • ^ (exponent)
    • () (parentheses)

    Examples

    fields=avg_seconds_viewed:video_seconds_viewed/video_view,video.name
    fields=avg_incomplete_ads:(ad_mode_begin-ad_mode_complete)/video_view,video.name
    fields=Video%20Views:video_view,video.name

    Sample request

    Sample response (to the request above)

    {
      "item_count": 110,
      "items": [
        {
          "avg_seconds_viewed": 2152.2519913106444,
          "video.name": "Flamingos",
          "video_seconds_viewed": 2972260,
          "video": "4825279519001",
          "video_view": 1381
        },
        {
          "avg_seconds_viewed": 14.016225448334756,
          "video.name": "Tiger",
          "video_seconds_viewed": 16413,
          "video": "4093643993001",
          "video_view": 1171
        },
        {
          "avg_seconds_viewed": 12.06,
          "video.name": "Zebra",
          "video_seconds_viewed": 9045,
          "video": "3851389913001",
          "video_view": 750
        },
        {
          "avg_seconds_viewed": 23.343065693430656,
          "video.name": "Sea-SeaTurtle",
          "video_seconds_viewed": 15990,
          "video": "1754276205001",
          "video_view": 685
        }
      ],
      "summary": {
        "avg_seconds_viewed": 274.27374399301004,
        "video_seconds_viewed": 3139063,
        "video_view": 11445
      }
    }

    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