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
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.
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 urlfilter 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:
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:
|
composite-filter | ( filter [boolOp
filter ]*) Where:
|
Use parentheses to logically group components of the filter value. For an example, see What Filters Can I Use?.