support Contact Support | system status System Status
Page Contents

    Migrating from the Analytics REST API to Brightcove Analytics API

    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.


    Page last updated on 28 Sep 2020