Discovery Editorial Query String Parameters

To enable you to adjust the results of the Ooyala Discovery recommendations, Ooyala provides query string parameters on the baseline APIs.

Note: Rather than constructing ad hoc requests (with individual parameters for each request), consider using discovery profiles to centralize your settings and recommendations behavior. Discovery profiles are defined configurations of settings created by you, which you then reuse by reference on the GET routes. For more information, see Discovery Profiles.

User account ids are distinct per provider. Two different providers can have a user with the same name, but these are treated as distinct users. The account_id you use with Ooyala APIs must be unique in your own systems. For privacy, Ooyala encourages that the value of account_id be some sort of GUID (global unique identifier), rather than a plain-text username or email address. For example, an acceptable account_id is to use a base64, URl-encoded, Secure-hash-algorithm-(SHA)-256 digest of the username or email address, salted with some secret string that only you know. This salt must not be reused for any of your vendors other than Ooyala. This ensures that neither Ooyala nor a "man-in-the-middle" hacker sniffing network traffic can translate back from your GUIDs to real usernames or passwords. The account_id must be less than 255 characters and must not contain reserved URL characters such as [/, &, |, or ]. In most cases, you do not need to explicitly create an account with Ooyala APIs; you simply refer to an account wherever an API request requires it.

You can use editorial query string parameters (such as filter_by and exclude_videos) to filter results by labels, express sequential relationships of videos, promote content by injecting it directly into results, and other functions. The parameters are available on all API routes that read (recommendation routes). In addition, some routes have additional query string parameters. For a detailed list of parameters, see Query String Parameters.

As compared to precomputed discovery profiles (see Discovery Profiles), the editorial functions are applied at the time of the API request and are considered "ad hoc" in this regard. They can be less performant than precomputed discovery profiles. If you find yourself reusing the same set of query string parameters and values on every request, consider using discovery profiles instead.

Another consideration is the possible cumulative effect of the editorial parameters. You can possibly end up excluding many recommendations coming from the machine learning algorithm. For example, suppose you limit the results (with limit=10 query string parameter) and then proceed to filter the 10 results. Depending on your filters, you could unintentionally exclude all the recommendations.