How to Export Your Data With the v2 Analytics API (Deprecated)

Warning: The v2 Analytics API has been deprecated. See Ooyala IQ Analytics for more details on the new v3 Analytics API.


The following information will guide you on retrieving and saving your analytics v2 data.

As we migrate customers from v2 Analytics to Ooyala IQ (v3 Analytics), you need to know the following:
  • All customers will have access to reprocessed data starting from January 1, 2014.
  • You will continue to have access to the old v2 Analytics API until June 30, 2016.
This means that if you need access to more than 1 year of historical analytics data, you need to export the data using the v2 APIs while they are still active.

Overview: The Ooyala v2 Analytics API

With the Ooyala v2 Analytics API you can easily create a report that will provide you with your analytics data. The results will be in JSON format. (JSON is a lightweight data-interchange format that is easy to read and write.)

To retrieve analytics results from a specific date range you simply need to define the type of result you need with the api call /v2/analytics/reports/, either in a terminal emulator such as Terminal on a Mac or in the Ooyala Scratchpad.

What is an API?

In computer programming. API (Application Programming Interface) is the name of a set of routines and protocols for software applications. An API expresses a software component in terms of its operations and results.

Where can I locate my API Credentials?

You can locate your API Key and Secret in the Backlot UI. Please use your API v2 credentials located in Backlot under the ACCOUNT>Developers tab.
Figure 1. Finding Your API Keys
Locating API Keys

How Does the API Work?

An Ooyala API call requires 4 basic elements: API Key, API Secret, a Signature and an Expiration time.

API calls are made via HTTP methods. The GET API call is used to retrieve data without directly modifying it and allows you to get a typed JSON document response based on the id of the object.

What are the Available Results I can Retrieve with the Ooyala v2 Analytics API?

On the v2 Analytics API there are 4 key qualifiers that you need to identify in order to retrieve your results:

asset_id: This value is referred to by different names depending on where you look for it. In the Backlot API, asset_id is the identifier for a specific asset. asset_id has the same value as the content ID found in the Backlot UI that represents a piece of content. The value is the same for all scenarios. asset_id can be used if you want to retrieve results for a specific asset. Alternatively, you can retrieve results for your account, which would include all of your assets.

date_range: Defines the date range for this report. Analytics is based on dates. You can define the date following the format (YYYY-MM-DD) or you can define a date range with (YYYY-MM-DD...YYYY-MM-DD).

Report Request: Defines the type of report you want to retrieve. Valid values include performance, sharing, engagement, and delivery.

Dimension: Dimensions are common criteria that are used to aggregate data, such as the date when the user activity occurred or the country where the users were located. Every Dimension also has “Drilldowns”, which allow you to filter your results by specific values for each dimension.

Common query string parameters and attributes can be found at Common Attributes and Query String Parameters (Deprecated).

How to Retrieve Your v2 Analytics Data

What is the API Call Format?

The v2 Analytics API follows a specific order on the body of the API.

For example, the API call: /v2/analytics/reports/account/performance/[:dimension/:drilldown]/:date_range

Should appear like the following if you want to get a performance report from 2011-01-01 to 2014-01-01:
Figure 2. API Call For Performance Report
Sample API Call

How Can I Use the Scratchpad to Save Reports?

The Scratchpad is a tool created by Ooyala that allows you to make API queries in your browser.

To retrieve an analytics report with the Scratchpad:
  1. Go to Ooyala API Scratchpad.
  2. Select “Your Account” in the Credentials section in the upper right corner of the page.
  3. Enter your v2 API credentials (API Key and Secret) in the Credentials section in the upper right corner of the page.
  4. In the Query field located on the left side of the page, enter your Analytics query. For example, if you would like to get the performance report from 2011 to 2014, copy and paste this query: /v2/analytics/reports/account/performance/total/2011-01-01...2014-01-01
  5. Select GET.
  6. Click Submit.
    Note: Your response appears in the response field.
  7. If you prefer to see your results in a larger browser window, copy the API URL shown in green above the Submit button into your browser. In this case, the URL would be
  8. Save the JSON by selecting File > Save As… in your browser. For information on how to convert JSON to CSV, see Converting Analytics JSON to CSV (Deprecated)

Additional Query Examples

For more details on how to form queries in Scratchpad and for specific analytics report types, see:
Note: To retrieve all data for a report type for your account, use the “total” query string parameter. You can find examples using “total” in each of the query example links mentioned above. “total” is used to retrieve all data for that particular report type for your account.
For example, the following query retrieves all performance data for the account over the date range 2011-08-01...2011-08-02.

How can I Create my own API Report?

You should only create your own API script if you are comfortable with the Ooyala API and have created scripts before or if you have the technical resources available who can modify the pre-made query to retrieve the data for you.

If you check the following snippet from our sample code that shows a terminal, you will be able to identify that we send the request of the API call using cURL. cURL makes http request where you can modify the parameters and the headers.
Figure 3. Sample API Report
API Report
Note: For more script examples, please check our support site documentation at Sample Code for Signing Requests.