Filters | Ooyala Help Center

Filters

Here are the complete reference details for filters for the v3 Analytics Reporting API.

The filter names are essentially the same as dimension names. Filters are specified with the filters= query string parameter. You can further refine the results with boolean operators. Surround filter values with single quotations (e.g. filters=asset=='asset_id'). Filter values are case-sensitive.

For examples of how to use filters, see What Filters Can I Use?.

Date Range Limitation

Note: For up to 2 filters you can set a date range of up to 1 year (366 days). For 3 filters you can set a date range of up to 1 month (31 days).

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

General Syntax of Reporting GET

The base syntax of the route and query string is as follows. For ease of reading, the single-line request has been split across several lines.

[GET] /v3/analytics/reports/?
            report_type=type
            &dimensions=dimensions
            &metrics=metrics
            &filters=filter_type=='filter_value'
            &start_date=date
            &end_date=date
            &other_parms
            &api_key=your_api_key

The required query string parameters (shown in bold) are report_type, start_date, and api_key.
If no dimensions are specified, total values across all dimension are returned.
For time ranges up to 1 month you can query by up to 3 dimensions at a time with unlimited rows of data. For time ranges greater than one month you can query by up to 2 dimensions at a time with up to 10,000 rows of data.
If no metrics are specified, all metrics are returned.

Note: You may pass the API key either as a query parameter or via the header X-API-KEY.

Note: At this time, the only valid value for report_type is performance.

Note: You can only use 1 dimension (url) for url queries.

General Syntax of Reporting Long Queries POST

For queries with query parameters that would exceed the HTTP GET specification limit of 230 characters , please use a POST request. Some browsers and http clients may support more than 230 characters, but we will not provide official support for queries that violate the HTTP GET specification. For POST requests, pass a JSON object in the request body instead of the query string parameters.

[POST] /v3/analytics/reports

{
    "report_type":"type",
    "dimensions":"dimensions",
    "metrics":"metrics",
    "filters":"(filter_type==\"filter_value\")",
    "start_date":"date",
    "end_date":"date",
    "other_parms":"other_param_value",
    "api_key":"your_api_key"
}

Filter Type	Meaning	Valid Values
`asset`	Filter data by asset. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	Any asset id associated with the provider or subproviders. The asset id can be `embed_code` or `external_ids` that you have entered in Backlot.
`country`	Filter data by country. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	Country code. See Country and Location Codes.
`region`	Filter data by geographic region. Our geographic reporting uses the definition of region provided by Quova. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	Any region string. You cannot specify `region` alone; you must also specify its `country`.
`dma`	Filter by DMA (defined marketing area, a US-centric concept not prominent in other parts of the world). Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	Any provider-defined DMA.
`state`	Filter data by state (i.e. the states within a country). In our geographic reporting, state is "the first-level administrative division" of a country, as defined by Quova. For example, you can filter so you only see data for plays in California. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	Any state string. You cannot specify `state` alone; you must also specify its `country`.
`device_type`	Filter by device type. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	See possible values in Codes for Platforms, Devices, and Operating Systems.
`domain`	Filter by internet domain.	Any domain string.
`url`	Filter data by a specific URL. Note: You can only use the `url`filter with the `url` dimension. You cannot use this filter with any other dimensions.	Any URL string. If you use a URL that is not tracked by Ooyala analytics, the API will return 0 data results.
`os`	Filter data by operating system. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	See possible values in Codes for Platforms, Devices, and Operating Systems.
`browser`	Filter data by browser. Note: The `browser` dimension applies only when `device_type` is `desktop`. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	See possible values in Codes for Platforms, Devices, and Operating Systems.
`pcode`	Filter data by the provider's pcode (Ooyala-supplied provider ID). For details, see Your API Credentials. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	Any pcode that is the current account (the provider executing the API call) or one of its sub-accounts.
`player_id`	Filter data by player id (of an Ooyala player). Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.
`label`	Filter data by label using the label id. Keep in mind the following points about working with labels in Ooyala IQ: Correlations among labels and associated videos are not pre-aggregated or pre-summarized (rolled up) but are resolved at the time of an API request. The Ooyala system aggregates based on a label's parent hierarchy. For example, imagine two labels, the parent "Cycle World" and its child label "Sport Bikes". A video labeled with the child "Sport Bikes" is rolled up into the parent label "Cycle World". If you request data for a label, the metrics returned are for that label and its child labels. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension.	You can use any defined label in Backlot. You can filter by multiple labels at a time. However, you can not mix the label filter with the asset type filter.
`asset_type`	Filter data by asset type. The asset type indicates whether the asset is a live channel ("live") or video-on-demand ("vod"). An asset will be considered of type live only if it was created using Ooyala's live platform. Live assets that got converted to video-on-demand before the end date of your reporting period will be counted as vod only, otherwise they will be counted as live. Note: This filter is not valid with the `url` dimension. You can only use `domain` and `url` filters with the `url` dimension. Also, this filter cannot be combined with the label filter.	The asset type can be "live" or "vod". Note that the asset type is case-sensitive and should be entered in all lowercase letters.

Boolean Operators; (AND) and | (OR)

The formal syntax of a filter is shown below.

filters= filter [boolOp filter]*

Symbol	Expansion
`filter`	`dimension-filter` or `composite-filter`
`dimension-filter`	`dimension` `op` `value` Where: `dimension` is a dimension name listed in Dimensions or a custom dimension name. `op` is `==` (equal to) or `!=` (not equal to). `value` is a single-quoted dimension value, like `os!='android'` (data with operating system Android).
`composite-filter`	`( filter [boolOp filter ]*)` Where: `filter` is defined above. `boolOp` is `;` (AND) or `\|` (OR). The boolean operator and second filter are optional and can be repeated without limit.

Symbol

Expansion

filter

dimension-filter or composite-filter

dimension-filter

dimension op value

Where:

dimension is a dimension name listed in Dimensions or a custom dimension name.
op is == (equal to) or != (not equal to).
value is a single-quoted dimension value, like os!='android' (data with operating system Android).

composite-filter

( filter [boolOp filter ]*)

Where:

filter is defined above.
boolOp is ; (AND) or | (OR). The boolean operator and second filter are optional and can be repeated without limit.

Grouping with Parentheses

Use parentheses to logically group components of the filter value. For an example, see What Filters Can I Use?.

Was this article helpful?

LEAVE FEEDBACK

Rate this article: