Analytics Reporting API Reference

version v3

https://api.ooyala.com/v3/analytics

Introduction

The v3 Analytics Reporting API relies on dimensions, metrics, and filters. These concepts are further detailed here. The v3 Analytics Reporting API is also sometimes referred to as simply the v3 Analytics API, or the Ooyala IQ API.

All reporting requests must be signed by your Ooyala-issued API key and secret key, and your GET requests must have an explicit expiration time. How to do this is detailed in this article on setup and mechanics for the v3 Analytics Reporting API.

Reports

Use this API endpoint for general requests related to the Ooyala IQ API.

/reports get post

get

Make a GET request to receive a report containing analytics information according to desired specifications.

For queries with parameters that exceed the HTTP GET specification limit of 230 characters, please use a POST request.

A business use case example is presented below, which queries how different brands are performing.

post

Receive a report containing analytics information according to desired specifications. Make a POST request instead of a GET request for queries with parameters that exceed the HTTP GET specification limit of 230 characters. Some browsers and HTTP clients may support more than 230 characters, but we do not provide official support for queries that violate the HTTP GET specification.

For POST requests, pass aJSONobject in the request body instead of query string parameters for a GET request.

For example, using curl, your request could take the form curl -H "Content-Type: application/json" -d '{your JSON here}' 'http://api.ooyala.com/v3/analytics/reports/?api_key=7ab06&expires=1299991855 &signature=ZWU3NGYzM2RkZDMxZTJmMjgxOTY0OThhOWM3YjcyOTg'

The business use case example below queries how different geographies are driving content traffic.

Make a GET request to receive a report containing analytics information according to desired specifications.

For queries with parameters that exceed the HTTP GET specification limit of 230 characters, please use a POST request.

A business use case example is presented below, which queries how different brands are performing.

Request
Response

Query Parameters

report_type: required (string)
A required parameter describing the type of report you wish to receive. For general information, set this parameter to performance. If you would like information on concurrent users, set this parameter to concurrent.
start_date: required (string)
The start date is specified as YYYY-MM-DD or YYYY-MM-DDTHH:MM. If no HH:MM time is specified, it is set to 00:00 by default. The start date's time, if specified, would be in the provider's time zone.
end_date: (string)
The end date is specified as YYYY-MM-DD or YYYY-MM-DDTHH:MM. If no HH:MM time is specified, it is set to 23:59 by default. The end date's time, if specified, would be in the provider's time zone. The end date itself is excluded from the time range, so that the time range is actually [start_date, end_date). The end_date parameter is required when report_type is set to concurrent.
metrics: (string - default: *, i.e., all metrics)
A list of comma-separated metric names. For a list of valid values, see the section on metrics.

Example:
```
metrics=plays_requested,displays
```
dimensions: (string)
A list of comma-separated dimension names. Results are grouped by the specified dimensions. If no dimensions are specified, total values across all dimensions are returned.

For a list of valid values, see the section on dimensions.

• For time ranges up to one month, you can query by up to three dimensions at a time with unlimited rows of data.

• For time ranges greater than one month, you can query by up to two dimensions at a time with 10,000 rows of data.

• You can only use one dimension for url queries.

• Multiple values must be comma-separated with no spaces. The order of the values is not important.

Example:
```
dimensions=device_type,dma
```
filters: (string)
Restricts the set of results by specified filter values.

• For up to two filters, you can set a date range of up to one year (366 days).

• For up to three filters, you can set a date range of up to one month (31 days).

For a list of valid values, see the section on filters.

• The value of filter_by must be URL-encoded.

• The value of the actual filter must be enclosed in single-quotation marks.

Example:
```
filters=country=='AU',device_type=='mobile'
```
time_segment: (string)
Specify the time-based segment for dimension data. This will sort blocks of data.

The time range automatically expands to the minimal time range that will fulfill the request. For example, specifying a start and end date for only today but with a time_segment of week causes the specified the start/end date to expand to cover the entire current week (in the provider's time zone). When there is no specified time_segment, the aggregate total for the specified dimensions is returned. When there is neither time_segment nor any specified dimension, the grand total for the time range is returned.

• Note: A week is defined as Monday — Sunday.

• Valid values are month, week, day, hour, and 15min.

• Note: Queries using the hour and 15min time segments can only be made with a date rage of up to 7 days. Queries using the hour and 15min time segments will not return metric information for segment_watched, uniq_displays, uniq_video_starts, percentage_watched, uniq_plays_requested, or any of the Discovery metrics.

Example:
```
time_segment=day
```
sort: (string - default: Sort by the metrics that are present in the query order, up to the first two.)
A list of comma-separated metrics to sort by. For multiple metrics, sorts by the metrics in the order the metrics are placed in the query. You can explicitly use as many sort metrics as you want (given that you have the metric), but default sorting has a limit of two metrics.

By default, sorting takes place in descending order. For ascending order, prefix a given metric with the + character. For example, sort= +video_starts.

• Note: It is recommended that you do not use segment_watched or percentage_watched as sorting metrics. Instead, use other metrics, like plays_requested. This is because there are different sort semantics for different metrics. For example, segment_watched and percentage_watched use the string (of the entire array) for sorting rather than a numeric sort. This means that if you sort by segment_watched, your results may not appear in numerical order. By contrast, plays_requested uses a numeric sort, which will provide you with clear results.

Example:
```
sort=plays_requested,displays,video_starts
```
limit: (integer - default: 1000)
Limit the number of records returned in the response, with a maximum limit of 1000. You can use the page parameter to paginate through all of your data. The limit and page parameters must be used in an API call to obtain the correct total count value.

Example:
```
limit=100
```
page: (integer - default: 0)
An index for pagination of your data. The data starts at page 0, so that page 1 is the second page. The limit and page parameters must be used in an API call to obtain the correct total count value.

Example:
```
page=1
```
api_key: required (string)
A user-specific key. It can be found, for instance, in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v3/analytics/reports/?report_type=performance&dimensions=asset,player_id&filters=player_id=='\''player1'\'' player_id=='\''player2'\''&metrics=plays_requested&start_date=2014-10-10&end_date=2014-10-20&api_key=7ab06&expires=1299991855&signature=ZWU3NGYzM2RkZDMxZTJmMjgxOTY0OThhOWM3YjcyOTg'

HTTP status code 200

A sample response to the business use case example which queries how different brands are performing.

Body

Type: application/json

Example:

{  
   "status": "OK",
   "results":[  
      {
         "data":[  
            {  
              "metrics":{  
                  "plays_requested":2500
               },
               "group":{  
                  "asset":"asset_id_1",
                  "player_id":"player1",
                  "name":"unknown",
                  "status":"unknown",
                  "type":"unknown"
               }  
            },
            {  
               "metrics":{  
                  "plays_requested":2200
               },
               "group":{  
                  "asset":"asset_id_2",
                  "player_id":"player2",
                  "name":"unknown",
                  "status":"unknown",
                  "type":"unknown"
               }      
            }
         ],
         "start_date":"2014-10-10T00:00Z",
         "end_date":"2014-10-20T00:00Z"
      }
   ],
   "status_code": "200",
   "total_count": "100",
   "result_count": "2"
}

HTTP status code 204

Successfully received, but no content. Returned by the Event Ping API. No response body is returned.

HTTP status code 400

Bad request. The request is incorrect. For example, it does not contain required query string parameters.

Body

Type: application/json

Example:

{  
    "status": "Invalid parameter",
    "statusCode": "400",
    "errors": ["filter has invalid syntax: invalid character . at position 4"]
}

HTTP status code 401

Not authorized. Either the credentials (Ooyala-provided API key and secret) are missing, or their values are not valid.

HTTP status code 403

Insufficient permissions. The credentials in the request do not have sufficient permission for data requested.

HTTP status code 429

Quota exceeded. The requester's quota of API calls has been exceeded. Quotas are described in the API Rate Limiting article.

HTTP status code 500

System error. Possible problem in the Ooyala system.

HTTP status code 503

Service unavailable. There is a temporary service outage.

For POST requests, pass aJSONobject in the request body instead of query string parameters for a GET request.

The business use case example below queries how different geographies are driving content traffic.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key. It can be found, for instance, in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

{  
   "report_type": "performance",
    "dimensions": "country",
    "filters": "((device_type=='tablet')) AND ((domain=='exampledomain.com'))",
    "metrics": "plays_requested",
    "start_date": "2014-10-10",
    "end_date": "2014-10-20",
    "sort": "plays_requested"
}

HTTP status code 200

A sample response to the business use case example which queries how different geographies are driving content traffic.

Body

Type: application/json

Example:

{  
   "status":"OK",
   "results":[  
      {  
         "data":[  
            {  
               "metrics":{  
                  "plays_requested":11000
               },
               "group":{  
                  "country":"us",
                  "countryName":"United States"
               } 
            },
            {  
               "metrics":{  
                  "plays_requested":5100
               },
               "group":{  
                  "country":"fr",
                  "countryName":"France"
               } 
            },
            { 
               "metrics":{  
                  "plays_requested":2000
               },
               "group":{  
                  "country":"gb",
                  "countryName":"United Kingdom"
               }
            },
            {  
               "metrics":{  
                  "plays_requested":2000
               },
               "group":{  
                  "country":"be",
                  "countryName":"Belgium"
               }
            },
            { 
               "metrics":{  
                  "plays_requested":1600
               }, 
               "group":{  
                  "country":"ca",
                  "countryName":"Canada"
               }
            },
            {  
               "metrics":{  
                  "plays_requested":1400
               },
               "group":{  
                  "country":"de",
                  "countryName":"Germany"
               }
            },
            {  
               "metrics":{  
                  "plays_requested":1100
               },
               "group":{  
                  "country":"ua",
                  "countryName":"Ukraine"
               }
            },
            {  
               "metrics":{  
                  "plays_requested":1000
               },
               "group":{  
                  "country":"se",
                  "countryName":"Sweden"
               }
            },
            {  
               "metrics":{  
                  "plays_requested":800
               },
               "group":{  
                  "country":"nl",
                  "countryName":"Netherlands"
               }
            },
            {  
               "metrics":{  
                  "plays_requested":600
               },
               "group":{  
                  "country":"it",
                  "countryName":"Italy"
               } 
            }
         ],
         "start_date":"2014-10-10T00:00Z",
         "end_date":"2014-10-20T00:00Z"
      }
   ], 
   "status_code":"200",
   "total_count":100,
   "result_count":10
}

HTTP status code 204

Successfully received, but no content. Returned by the Event Ping API. No response body is returned.

HTTP status code 400

Bad request. The request is incorrect. For example, it does not contain required query string parameters.

Body

Type: application/json

Example:

{  
    "status": "Invalid parameter",
    "statusCode": "400",
    "errors": ["filter has invalid syntax: invalid character . at position 4"]
}

HTTP status code 401

Not authorized. Either the credentials (Ooyala-provided API key and secret) are missing, or their values are not valid.

HTTP status code 403

Insufficient permissions. The credentials in the request do not have sufficient permission for data requested.

HTTP status code 429

Quota exceeded. The requester's quota of API calls has been exceeded. Quotas are described in the API Rate Limiting article.

HTTP status code 500

System error. Possible problem in the Ooyala system.

HTTP status code 503

Service unavailable. There is a temporary service outage.

Analytics Reporting API Reference

version v3

Introduction

Reports

/reports get post

get /reports

Query Parameters

Body

HTTP status code 200

Body

HTTP status code 204

HTTP status code 400

Body

HTTP status code 401

HTTP status code 403

HTTP status code 429

HTTP status code 500

HTTP status code 503

post /reports

Query Parameters

Body

HTTP status code 200

Body

HTTP status code 204

HTTP status code 400

Body

HTTP status code 401

HTTP status code 403

HTTP status code 429

HTTP status code 500

HTTP status code 503