Ooyala Analytics API Reference

Overview

The Ooyala Analytics API provides a programmatic interface to retrieve data on various video and channel metrics. Each query requires a mode, date range, result granularity, and an output format. The two modes for the API are per-account level and per-video/channel. The account-level interface provides for queries such as "Top 50 played videos" and "Top 10 videos by time watched" on an account-wide basis. The content-level interface provides information on a specific video or channel and can include a variety of metrics explained in detail later in this document. Result granularity depends on the specific report but includes day, week, month, and total options. Output format options are XML, CSV, and JSON.

Query Option Reference

A flexible set of options that can be passed to the Analytics API for customized statistics.

Query Examples

Analytics API use cases with sample query strings and their results.

Query Signing

Detailed instructions on signing parameters to create a unique signature that is required for all analytics requests.

Ruby Library and Example Code

A Ruby reference for accessing analytics statistics.

Query Option Reference

There are four required parameters for a query (format, granularity, date, method) and a number of optional parameters some of which depend on the query method.

Caveats

Pagination

When using a method of account.videoTotals, account.geoTotals, account.domainTotals, or video.domainTotals, the result can have thousands of entries. To limit the result size we truncate at 500 entries and return a <nextPageID> element with a pointer to the next page of results. A nextPageID of -1 indicates there are no further results.

Requirements for video.* method calls

When making a request using a video.* method, the video parameter is required. This parameter accepts a single video embed code or multiple embed codes in a comma-separated list. The video parameter will be ignored for any non-video.* methods.

Required Parameters

Note: Geographic and Domain reporting are only available in Professional and Enterprise accounts.

Optional Parameters

Query Examples

Example:

Query for displays, plays, and timeWatched for a specific video from August 18 to 19, 2008:

http://www.ooyala.com/api/analytics?pcode=<pcode>date=2008-08-18%2C2008-08-19&expires=<expiration>&fields=displays%2Cplays%2CtimeWatched&format=xml&granularity=day&limit=2&method=video.totals&video=<embedCode>&signature=<signature>

Result:

<result>
  <video>
    <embedCode>A5bjM6ugP5LWOxnmXxgk6fjJ22Kn36dw</embedCode>
    <day>
      <date>2008-08-18</date>
      <displays>143</displays>
      <uniqueDisplays>122</uniqueDisplays>
      <plays>104</plays>
      <uniquePlays>96</uniquePlays>
      <timeWatched>16542.00</timeWatched>
    </day>
    <day>
      <date>2008-08-19</date>
      <displays>185</displays>
      <uniqueDisplays>147</uniqueDisplays>
      <plays>123</plays>
      <uniquePlays>87</uniquePlays>
      <timeWatched>21846.00</timeWatched>
    </day>
  </video>
</result>
Example:

Query for domain information, from July 1, 2008 to September 1, 2008, limited to the top two embed domains:

http://www.ooyala.com/api/analytics?pcode=<pcode>date=2008-07-01%2C2008-09-01&expires=<expiration>&format=xml&granularity=total&limit=2&method=account.domainTotals&signature=<signature>

Result:

<result>
  <account>
    <domain>
      <name>example.org</name>
      <displays>104</displays>
      <plays>46</plays>
      <replays>23</replays>
      <timeWatched>1.86</timeWatched>
    </domain>
    <domain>
      <name>example.net</name>
      <displays>2</displays>
      <plays>2</plays>
      <replays>0</replays>
      <timeWatched>0.00</timeWatched>
    </domain>
  </account>
</result>
Example:

Query for account-wide country data since the beginning of the month, limited to the top 40 countries, ordered by timeWatched, decending, with output in csv: 

http://www.ooyala.com/api/analytics?pcode=<pcode>&date=month&expires=<expiration>&format=csv&
granularity=total&limit=40&method=account.geoTotals&orderBy=timeWatched%2Cdesc&signature=<signature>

Result: 

code,name,displays,plays,replays,timeWatched
US,United States,25127,10752,2791,129.57
TR,Turkey,3446,2130,90,21.05
GB,United Kingdom,2703,1504,441,14.93
DE,Germany,1653,766,178,9.91
CA,Canada,1229,594,159,8.31
BR,Brazil,819,472,74,6.09
FR,France,833,432,97,5.39
JP,Japan,745,329,87,4.90
MX,Mexico,510,265,48,4.45
IT,Italy,830,408,63,4.22
RU,Russian Federation,655,358,39,4.05
NL,Netherlands,622,312,68,3.66
AU,Australia,584,311,94,3.54
CN,China,375,197,67,2.89
CH,Switzerland,357,164,36,1.92
PL,Poland,225,144,42,1.78
SE,Sweden,322,148,27,1.61
AR,Argentina,191,110,28,1.59
HK,Hong Kong,206,94,13,1.19
TW,Taiwan,186,90,10,1.18
LV,Latvia,95,56,21,0.80
GR,Greece,92,55,21,0.75
TH,Thailand,65,44,21,0.72
ZA,South Africa,79,36,14,0.66
BE,Belgium,130,70,18,0.64
UA,Ukraine,63,33,12,0.64
NZ,New Zealand,107,55,13,0.55
Example:

Query for all behavior-related viewership data for one video over the account lifetime. Fields percentWatched, and segmentWatched are outputted in xml: 

http://api.ooyala.com/api/analytics?pcode=<pcode>&date=all&expires=<expiration>&fields=percentWatched,segmentWatched&format=xml&granularity=total&limit=1&method=video.behavioral&video=<embedCode>&signature=<signature>

Result: 

<result>
  <video>
    <embedCode>kxYm06gFKXEleIHdyXNKeefx-QAu2yVp</embedCode>
    <title>how_to_fold_a_T_shirt.wmv</title>
    <percentWatchedCounts>
      2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,1,1,1,1,1,1,1
    </percentWatchedCounts>
    <segmentWatchedCounts>
      2,4,4,3,3,3,3,3,3,3,3,3,2,2,2,2,2,4,4,4,4,4,4,4,4,4,3,3,3,3,3,3,3,2,2,2,2,2,2,2,2
    </segmentWatchedCounts>
  </video>
</result>
Example:

Query for video totals across the account over the account lifetime and outputted in json: 

http://api.ooyala.com/api/analytics?pcode=<pcode>&date=month&expires=<expiration>&format=json&granularity=total&method=account.videoTotals&signature=<signature>

Result: 

{"account": {"video": [{"embedCode": "kxYm06gFKXEleIHdyXNKeefx-QAu2yVp", "title": "how_to_fold_a_T_shirt.wmv", "displays": 2, "plays": 2, "replays": 1, "timeWatched": "0.02", "pw25": 2, "pw50": 2, "pw75": 2, "pw100": 1}]}}

Signature Generation

API queries are required to be signed in order to ensure account security. We present these steps as an example of generating a signed API request. The query produced in this example is valid and illustrates how to compose and sign a qualified request. A detailed signing example is available here

Account-specific codes for Provider ID (pcode) and Secret (secret) can be found in Backlot Account tab under Developers. The pcode is 28 characters long, and the Secret Code is 40 characters long. Both are case sensitive and include alphanumeric characters, dashes (-), and underscores (_). These codes are required to generate a signature for each request to and from the Ooyala servers.

Example: 
Partner Code: lsNTrbQBqCQbH-VA6ALCshAHLWrV
Secret Code: hn-Rw2ZH-YwllUYkklL5Zo_7lWJVkrbShZPb5CD1
Note: These parameters point to a shared account accessible via API to any Backlot partner for preliminary testing. Content and metadata uploaded to this account is visible to all users.

The pcode, secret code, all required parameters, and all included optional parameters are used to generate a SHA-256 signature for the call. We present this example on how to generate a signature and URI-encode the parameters for the call.

  1. Begin with the 40 character Secret Code from the Developers area of your Backlot Account tab. 
    hn-Rw2ZH-YwllUYkklL5Zo_7lWJVkrbShZPb5CD1
  2. Sort the parameter names alphabetically and append <name>=<value> pairs to the string. The SHA-256 signature is generated with the result, which does not include the pcode.This example uses date=all, format=xml, granularity=day, and method=account.totals. 
     hn-Rw2ZH-YwllUYkklL5Zo_7lWJVkrbShZPb5CD1date=allexpires=4102448461format=xmlgranularity=daymethod=account.totals
  3. Generate an SHA-256 digest in base 64 format on this string, truncate the string to 43 characters and drop any trailing '=' signs. URI encode the signature specifically '+','=', and '/'. This example produces a signature of 
    uyKVgVILbgPOgp3ly5jU5NVRQsx2qaIoz%2FesiqyCJwY
  4. To create the final query URL, begin with http://www.ooyala.com/api/analytics? and the Partner Code from the Developers area of your Backlot Account tab. Append the query parameters in alphabetic order, separated with & and end with signature=<signature> to include the digest computed in Step 3.

    Note: All parameters must be URI-escaped before being added to the query. Parameters should be URI-escaped in the query, not when generating the signature. 

     http://api.ooyala.com/api/analytics?pcode=lsNTrbQBqCQbH-VA6ALCshAHLWrV&date=all&expires=4102448461&format=xml&granularity=day&method=account.totals&signature=uyKVgVILbgPOgp3ly5jU5NVRQsx2qaIoz%2FesiqyCJwY

Ruby Library and Example Code

Library 

require "rubygems"
require "base64"
require "cgi"
require "digest/sha2"
require "open-uri"

module Ooyala
  module Analytics
    module API

      # You can find your partner and secret code under the "Account > API Settings"
      # subtab in Backlot.
      OOYALA_PARTNER_CODE = "<Your Partner Code>"
      OOYALA_SECRET_CODE = "<Your Secret Code>"

      def self.query(params)
        return send_request("analytics", params)
      end  "method" => "account.geoTotals",


      private

      def self.send_request(request_type, params)
        # Add an expire time to the query if one was not provided
        params["expires"] ||= (Time.now.to_i + 900).to_s

        string_to_sign = OOYALA_SECRET_CODE
        url = "http://www.ooyala.com/api/#{request_type}?pcode=#{OOYALA_PARTNER_CODE}"

        params.keys.sort.each do |key|
          string_to_sign += "#{key}=#{params[key]}"
          url += "&#{CGI.escape(key)}=#{CGI.escape(params[key])}"
        end

        digest = Digest::SHA256.digest(string_to_sign)
        signature = Base64::encode64(digest).chomp.gsub(/=+$/, "")

        url += "&signature=#{CGI.escape(signature)}"
        return open(url).readlines
      end
    end
  end
end

Sample Queries

augVideoData = Ooyala::Analytics::API::query(
  "date" => "2008-08-18,2008-08-19",
  "fields" => "displays,plays,timeWatched",
  "format" => "xml",
  "granularity" => "day",
  "limit" => "2",
  "method" => "video.totals",
  "video" => "A5bjM6ugP5LWOxnmXxgk6fjJ22Kn36dw")

domainVideoInfo = Ooyala::Analytics::API::query(
  "date" => "2008-07-01,2008-09-01",
  "format" => "xml",
  "granularity" => "total",
  "limit" => "2",
  "method" => "account.domainTotals")

accountTop40Countries = Ooyala::Analytics::API::query(
  "date" => "month",
  "format" => "xml",
  "granularity" => "total",
  "limit" => "40",
  "orderBy" => "timeWatched,desc",
  "output" => "csv")