Limited Availability - Do not share this document

This topic is obsolete

This topic provides guidance on moving from the Ooyala Analytics REST API to the Video Cloud Analytics API.

Introduction

The Video Cloud Analytics API is quite similar to to the Ooyala Analytics REST API.

Note also that the Analytics Module in Video Cloud Studio includes a robust Custom Report Builder that in many cases may make it unnecessary to use the API at all.

The sections below correspond to the different aspects of the two APIs:

Authentication

Authentication of Brightcove API requests is handled slightly differently than that for the Ooyala REST APIs. See Authentication for Brightcove API Requests for details.

Reports

The single /reports endpoint for Ooyala Analytics REST API corresponds very closely to the Brightcove Analytics API /data endpoint. The main difference is that the Ooyala API allows both GET and POST, the latter used to pass some data in the request body rather than URL params, allowing for some longer data strings.

Parameters

The parameters for requests are similar for the two APIs. They are detailed in the table below to show you where the differences lie.

Parameters
Ooyala Parameter Brightcove Parameter Docs
none accounts - included as a parameter to all reports on multiple accounts Overview of Dimensions, Fields, and Parameters
report_type None, but the Brightcove API offers some additional endpoints for engagement and live analytics reports Overview: Analytics API
start_date from the two params are similar and both accept values in the form YYYY-MM-DD; the Brightcove param also accepts epoch dates in milliseconds and relative dates such as -3d Overview of Dimensions, Fields, and Parameters
end_date to the two params are similar and both accept values in the form YYYY-MM-DD; the Brightcove param also accepts epoch dates in milliseconds and relative dates such as -3d Overview of Dimensions, Fields, and Parameters
metrics fields - the two params are essentially identical; the Brighcove API also uses metrics for Live Analytics requests; see Metrics for information on what metrics are available Overview of Dimensions, Fields, and Parameters
dimensions dimensions - the two params are essentially identical; the Brighcove API also uses metrics for Live Analytics requests; see Dimensions for information on what dimensions are available Overview of Dimensions, Fields, and Parameters
filters where - apart from the name, the two params are essentially identical; see Filters below for more information Overview of Dimensions, Fields, and Parameters
time_segment none - the Brightcove API does have date and date_hour dimensions that provide some similar time-segmenting, and also engagement endpoints for periods within the previous 32 days, which provide views over each 100th part of the video Overview of Dimensions, Fields, and Parameters
sort sort the params are identical except that the Ooyala API allows sorting on multiple metrics Overview of Dimensions, Fields, and Parameters
limit limit - the params are identical except for the 1000 limit on the Ooyala API param Overview of Dimensions, Fields, and Parameters
page offset - the params take different values but work similarly for paging of datasets Overview of Dimensions, Fields, and Parameters
none reconciled - because analytics data comes from different sources on different schedules, the Brightcove API puts recent analytics data into an "unreconciled" bucket while it is still being updated, and transfers it to a "historical" bucket; the param allows you to choose between these buckets Overview of Dimensions, Fields, and Parameters
none bucket_limit - applies only to Live Analytics requests; together with bucket_duration, these function in a way somewhat similar to the Ooyala API time_segment param Overview of Dimensions, Fields, and Parameters
none bucket_duration Overview of Dimensions, Fields, and Parameters

Dimensions

The Ooyala and Brightcove Analytics APIs both group data into buckets called "dimensions". They are used in similar ways, but the APIs have somewhat different rules as to how multiple dimensions can be combined, and Brightcove has a broader set of dimensions. See Supported dimension combinations for details on the Brightcove API. The table below provides a detailed comparison.

Dimensions
Ooyala Dimension Brightcove Dimension Docs
asset video - the Brightcove video dimension covers only VOD assets; there is also a live_stream dimension Video Dimension
country country - dimensions are essentially identical Country Dimension
region region - dimensions are essentially identical, except that the Brightcove dimension includes US states Region Dimension
dma none n/a
state region - the Brightcove API includes US states in the region dimension Region Dimension
device_type device_type - dimensions are essentially identical Device Type Dimension
domain destination_domain Destination Domain Dimension
url device_os - essentially the same Device OS Dimension
os destination_domain - not exactly the same, but the closest equivalent Destination Domain Dimension
pcode account Account Dimension
player_id player Player Dimension
none browser_type Browser Type Dimension
none date Date Dimension
none date_hour Date-Hour Dimension
none device_manufacturer Device Manufacturer Dimension
none referrer_domain Referrer Domain Dimension
none search_terms Search Terms Dimension
none social_platform Social Platform Dimension
none source_type Source Type Dimension

Filters

Filters works pretty much identically in the two APIs, specified in terms of:

      
        // Ooyala
        filter={dimension1}=={value1};{dimension2}=={value2}
      
        // Brightcove
        where={dimension1}=={value1};{dimension2}=={value2}

Metrics

The metrics (for the Brightcove API: fields) returned in reports varies according to the dimension(s) requested for Brightcove Analytics API. you can use the tool embedded in Dimensions and Fields to see which fields can be returned for a particular dimension or combination of dimensions.

Note that while the Ooyala API returns all metrics if none are specified, but the Brightcove API returns only a small set of default metrics which vary by the dimension (combination) unless you include the fields in the request.

Brightcove fields contain equivalents for all the Ooyala metrics except for:

  • uniq_plays_requested
  • uniq_displays
  • uniq_video_starts

The Brightcove Analytics API can also return number of other metrics not available in Ooyala analytics.