Filtering Results: filter_by

Use filter_by to constrain results to specific filters.

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.

Ooyala Discovery can filter results based on specific labels or shared labels. With specific labels, you specify one or more labels that must be assigned to content within the results. With shared labels, you specify a label with a value that must be shared between the video being watched and the recommendations.

To filter recommendations:

  1. If you want to specify labels, use the filter_by query string parameter and enter a comma-separated list of labels. The following example returns the two most popular videos for the day that have the cat or piano labels.
    Note: The comma (,) in the filter_by value indicates logical OR.
    [GET] /v2/discover/trending/top?countries=all&time=now&window=day&limit=2&filter_by=cat,piano    
    Backlot returns a response similar to the following.
    		{
    		  "results": [
    		    {
    		      "name": "Cat Piano Video #1456",
    		      "description": "More cats playing piano!",
    		      "embed_code": "embed_code",
    		      "external_id": "external_id",
    		      "preview_image_url": "image_urls",
    		      "duration": "91000",
    		      "hostedAtURL": null,
    		      "bucket_info": "bucket_info_id",
    		      "reason": "top"
    		    },
    		    {
    		      "name": "Cat Video #1457",
    		      "description": "Even more cats playing piano!",
    		      "embed_code": "embed_code",
    		      "external_id": "external_id",
    		      "preview_image_url": "image_urls",
    		      "duration": "91000",
    		      "hostedAtURL": null,
    		      "bucket_info": "bucket_info_id",
    		      "reason": "top"
    		    }
    		  ]}
  2. If you want the source and recommended videos that share sublabels, use the filter_by query string parameter and enter the sublabels to share. The following example returns the two most popular videos for the day that share sublabels with the current video (animal/cat or instrument/piano or language/English).
    Note: The comma (,) in the filter_by value indicates logical OR.
    [GET] /v2/discover/trending/top?countries=all&time=now&window=day&limit=2&filter_by=
    shared:animal,shared:instrument,shared:language    

    Backlot returns a response similar to the following.

    		{
    		  "results": [
    		    {
    		      "name": "Cat Piano Video #1456",
    		      "description": "More cats playing piano!",
    		      "embed_code": "embed_code",
    		      "external_id": "external_id",
    		      "preview_image_url": "image_urls",
    		      "duration": "91000",
    		      "hostedAtURL": null,
    		      "bucket_info": "bucket_info_id",
    		      "reason": "top"
    		    },
    		    {
    		      "name": "Cat Video #1457",
    		      "description": "Even more cats playing piano!",
    		      "embed_code": "embed_code",
    		      "external_id": "external_id",
    		      "preview_image_url": "image_urls",
    		      "duration": "91000",
    		      "hostedAtURL": null,
    		      "bucket_info": "bucket_info_id",
    		      "reason": "top"
    		    }
    		  ]}
  3. Get the information from each result to generate web page content. The following example contains simple HTML content.
    <div class="sidebar">
        <h4 class="sidebar-head">Popular Now</h4>
        <ul>
            <li>
                <p><a href="/video/Jr8fdsNDrcK-TYHGlFIZuTlPoDZ_QkW3">Cat Video #1456</a></p>
                <p>More cats playing piano!</p>
            </li>
            <li>
                <p><a href="/video/3556csNDrcK-ZaRTYhuTlPoDZ_tyrD">Cat Video #1457</a></p>
                <p>Even more cats playing piano!</p>
            </li>        
        </ul>
    </div>   
Note:

Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. To launch the scratchpad, go to Ooyala API Scratchpad.

Was this article helpful?