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 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:
  • 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.
Grouping with Parentheses

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

Parent topic: Parameter Reference
https://help.ooyala.com/sites/all/libraries/dita/en/video-platform/api/analytics_v3_api_reporting_filters.html

Was this article helpful?

Rate this article:
AAA