v3 Analytics Reporting API

This section details the v3 Analytics Reporting API, also referred to as the v3 Analytics API and the Ooyala IQ API.
The v3 Analytics Reporting API relies on the following basic concepts, almost all of which are described in How Ooyala IQ Works in the Ooyala IQ User Guide:
  • Dimensions: common criteria that are used to aggregate data, such as the date on which the user activity occurred or the country where the users were located.
  • Metrics: measurements of individual events related to your content, such as video plays requested or pauses.
  • Filters: dimension values that constrain the retrieved data. For example, you can retrieve data for a specific type of device, a specific video, or specific dates.

Best Practices

The following best practices will ensure that you have optimal query performance and speed.

  • Whenever possible, if you have to retrieve a lot of data, chunk your queries into smaller bits. This makes the query much faster. For example:
    • Instead of running a query on one year of data, run a query on every quarter (4 months) and combine the CSV data afterward.
    • Instead of running a query on all of the domains you want to investigate, run a query on each domain separately and combine the CSV data afterward.
    • Instead of running a query on all of the countries you want to investigate, run separate queries on small groups of countries and combine the CSV data afterward.
  • Use multi-dimensional queries only as necessary. When you do perform multi-dimensional queries (group your results by up to 3 dimensions), try to restrict the query with filters to improve query performance.
  • You can run up to 300 calls to the v3 Analytics API per minute. However, for optimal performance we recommend that you, run one query at a time as we build up capacity for more customers.

Request Signing and Expiration

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

Note: For ease of reading, the majority of examples here are not signed requests.

Endpoint for Requests

All your reporting GET requests must be made to the http://api.ooyala.com/ endpoint.