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

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 will 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. It will be ignored for any non-video.* methods.

Required Parameters

  • date - Date range for the result. One of:
    • keywords - today, yesterday, week (current week), month (current month) or all (account lifetime or 2 years, whichever is less).
    • specific date - YYYY-MM-DD
    • range - lastX where X is a number. Ex: last 10 days (Granularity=day&Date=last10), last 6 weeks (Granularity=week&Date=last6) or a range defined by two dates: YYYY-MM- DD, YYYY-MM-DD
  • expires - Number of seconds from the epoch at which time the query URL will expire.
  • format - Query result format. One of {xml, csv, json}.
  • granularity - Granularity of data in the result. One of {day, week, month, total}.
  • method – Specify whether the query is based on an account, content, or domain basis. One of:
    • account.videoTotals – Video summary for an account. Pageable.
    • account.totals – Account summary statistics.
    • account.geoTotals – Country-based statistics on viewership. Pagable.
    • account.domainTotals – Domain-based statistics on viewership. Pagable.
    • domain.totals – Statistics for a specific domain. Can be account-based or include an embed code for a specific video using the video parameter.
    • video.totals - All stats for a given embed code. Can provide a maximum of 100 comma- separated embed codes to query against.
    • video.domainTotals - All statistics for a given video, grouped by domain. Can provide a maximum of 100 comma-separated video IDs. The Limit parameter can be used to limit the number of domains included in the result (500 is the max). The OrderBy parameter will order the list of domains returned. Pagable.
    • video.behavioral - Detailed behavioral stats (percentWatched and segmentWatched) for a video. Can provide a maximum of 100 comma-separated video IDs. This method includes counts for every 2.5% of the video watched, instead of every 25% as in video.totals. Requires the "fields" parameter to be "percentWatched", "segmentWatched" or both (separated by a comma).

Optional Parameters

  • domain – Specify a domain to filter on when using the domain.totals method.
  • fields – Specify one or more fields to include in the result by a comma-separated list from:
    • embedCode – embedCode of the content
    • title – title of the content
    • displays – uniqueDisplays available for day, week, month
    • plays – uniquePlays available for day, week, month
    • replays – uniqueReplays available for day, week, month
    • timeWatched – video delivery time in hours
    • percentWatched, segmentWatched – Only applicable to video.behavioral queries
    • contentType – video, channel, or channelSet
  • limit – Number of rows to be returned. Only relevant for Geo, Domain, and account.videoTotals queries. The default is 500.
  • orderBy – The value and order on which to sort the result. "value,[asc|desc]" e.g.: "displays,asc"
  • pageID – If the query method supports pagination, specify the page to return. Should be the value of the <nextPageID> element included in a truncated query result.
  • contentType – Type of content to include in the result. One of {video, channel, channelSet}. Only applies to queries using the account.videoTotals method.
  • video – If using a video.* method, specify the video embed code to query against. Multiple embed codes can be specified with a comma-separated list.

Query Examples

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

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

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>

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

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

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>

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

http://www.ooyala.com/api/analytics?pcode=NwMTor10B3GEDdZTkMRSUEkyQ9VK&date=month&expires=1222656721&format=csv&
granularity=total&limit=40&method=account.geoTotals&orderBy=timeWatched%2Cdesc&signature=
GJjgBxPplOBAF3sYXIg4FSx0SLkG2h%2BN7VlzQw50%2Bzo

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

Query Signing

Analytics API queries must be signed to ensure account security. We present these steps as an example of generating a signed API request. The query produced in this example is not valid but illustrates how to compose and sign a qualified request. A detailed example in Ruby follows at the end of the document.

  1. Begin with the 40 character Secret Code from the Developers area of your Backlot Account tab. 
    nEHVcepTobY2O07FxvWFBQ7m6jDFKOM6nZNuAUPD
  2. Append the query parameters in the form of <name>=<value> pairs to the string, alphabetically based on <name>. This example uses date=last5, format=xml, granularity=day, method=Video.totals, and video=A5bjM6ugP5LWOxnmXxgk6fjJ22Kn36dw. 
    nEHVcepTobY2O07FxvWFBQ7m6jD3KOM6nZNuAUPDdate=last5expires=3093013925format=xm
lgranularity=daymethod=Video.totalsvideo=A5bjM6ugP5LWOxnmXxgk6fjJ22Kn36dw
  3. Generate an SHA-256 digest in base 64 format on this string, dropping any trailing '=' signs. This example produces a signature of 
    A8suGqvS2qD6pYJbF9ceSuenjJtNQreDs7ksnbWjP4Q
  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= to include the digest computed in Step 3.

    Note: All parameters must be URI-escaped before being added to the query string. 

    http://www.ooyala.com/api/analytics?pcode=NwMTor10B3GEDdZTkMR8UEkyQ9VK&date=last5&expires=3093013925&format=
xml&granularity=day&method=Video.totals&video=A5bjM6ugP5LWOxnmXxgk6fjJ22Kn36dw&signature=
A8suGqvS2qD6pYJbF9ceSuenjJtNQreDs7ksnbWjP4Q

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

      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",
  "method" => "account.geoTotals",
  "orderBy" => "timeWatched,desc",
  "output" => "csv")