Searching for Videos with the Media API

This document describes how to use the search_videos method in the Media API to locate videos in your Media Library. The Read methods in the Media API include a set of methods (find_video, find_video_by_id, etc.) that enable you to make comparatively simple searches. The search_videos method enables more complex searches. Using search_videos, you can search by many combinations of fields in the video object (including custom fields), and combine search terms to return videos if any, all, or none of the search terms match.

The search_videos method

The Media API Reference describes all the parameters used with the search_videos method, as well as all the properties of the ItemCollection object that is returned by the search_videos method. This method has the following signature:

search_videos(token:String, all:List, any:List, none:List, sort_by:List, exact:Boolean, 
    page_size:Integer, page_number:Integer, get_item_count:Boolean, 
    video_fields:List, custom_fields:List, media_delivery:Enum, output:Enum):ItemCollection

This is a read method, so use the Media API read token for your account.

Search fields

You can search for values in combinations of the searchable fields of a Video. You specify the fields and values you want to search for in the field:value format. For example, to search for videos whose name includes alien:

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=display_name:alien

If you omit the field name, the method searches the videos' name, short description, and long description. For example, to search for videos whose name, short description, or long description includes the word "alien":

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=alien

Searchable fields

With the search_videos method, you can search for the following fields of Videos:

field name in search_videos command	property name in Video object
display_name	displayName
reference_id	referenceId
tag	tag
custom_fields	customFields
search_text	searchText

Using the search_text field name is the equivalent of searching the displayName, shortDescription, and longDescription fields of the video, and is also the equivalent of omitting the field name altogether.

Custom fields in search terms

The custom_fields field name is the equivalent of searching all of the custom metadata fields defined for your account. When you set up custom fields, you should avoid using field names that are the same as the standard video or playlist field names. If you search a custom field that has the same name as a standard field, only the standard field will be searched. Note that the name category is reserved as a standard field, so if you search for a custom field named category, the search will not cover the custom field.

Special characters support for the searchText field

For exact searches, that is, searches wherein the exact argument is set to true, the percentage, dash, forward slash, parenthesis, underscore, greater than, and less than characters are fully supported. Exact searches that include these characters, return all text containing your exact criteria. For fuzzy searches, that is, searches wherein the exact argument is set to false, the percentage, dash, forward slash, parenthesis, underscore, greater than, and less than characters are ignored and have no affect on the search. So a fuzzy search for He's 100% Dog returns the same results as a fuzzy search for He's 100 Dog.

Caution: Entering these special characters ONLY as criteria when searching for searchText with exact set to false returns ALL videos. So a search for % in an inexact search of the searchText field, will return all videos.

Search criteria

Use the all, any, and none arguments to specify the search criteria to use.

• Use all to specify that all of the field/value pairs must be present in a video.
• Use any to specify that at least one of the field/value pairs must be present in a video.
• Use none to specify that none of the field/value pairs must be present in a video.

You can combine the all, any, and none arguments for complex search behavior. For example, to search for videos whose name includes jobs, but not Steve:

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=display_name:jobs&none=display_name:steve

Note: to search on mutiple terms, include the all, any, or none parameters multiple times: 

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &any=display_name:jack&any=display_name:jill

Search terms are case-insensitive; including any of the following search terms will yield the same results: gibbous, GIBBOUS, Gibbous.

The exact argument specifies whether the values in the video must match exactly the values in the search criteria. If you use exact=false (which is the default), the values don't need to match exactly. For example, with exact=false, a search for the value run will also return hits with the values runs and running. The matching is based on linguistic stem rules, rather than partial word matches; a search for the value run will not return words like runt or rung. In this release, this feature functions only for English; if the region of your account is not the United States, all searches will be treated as if exact=true.

Limiting the result set

The search_videos method returns an ItemCollection object that contains all of the videos that match the search criteria. For best performance, you should limit the result set both by the number of videos returned (using paging), and by the video properties returned (using the video_fields argument).

Using paging

The videos returned by the search_videos method are grouped in pages; the page_size argument lets you specify the number of videos returned on each page. The maximum page size is 100; if you do not set this argument, or if you set it to an integer greater than 100, your results will come back as if you had set page_size=100.

The page_number argument lets you access a specific page in a large result set. The page_number is zero-based, so if you want the 4th page from your result set, use page_number=3.

The get_item_count argument, if true, makes the method return the total number of videos in the result set. You can use this number to figure out how many pages are in the result set.

Using video_fields

The video_fields argument enables you to specify which fields are populated in the Video objects returned in your result set. By using this argument, you can ensure that you get only the information you actually want to use.

If you are using custom metadata fields, you can use the optional custom_fields argument to specify which custom metadata fields you want to be returned. In addition, you can retrieve all of the custom metadata fields defined for videos in your account by including the value customFields in your video_fields argument.

Sorting the result set

You can sort the result set using the sort_by argument. This argument takes a list; each item in the list is a pair consisting of a field and a SortOrderType (one of ASC for ascending order or DESC for descending order). You can sort by the following fields: DISPLAY_NAME, REFERENCE_ID, PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, START_DATE, PLAYS_TRAILING_WEEK, PLAYS_TOTAL. For example:

• To sort the videos in your result set from newest to oldest, use this sort_by argument: sort_by=CREATION_DATE:DESC.
• To sort first by most recent published date and then by most played, use this sort_by argument: sort_by=PUBLISH_DATE:DESC,PLAYS_TOTAL:DESC.

Bear in mind that dates are stored and searched in milliseconds, so two videos that may have the same published date in the Media module are likely to have different published dates for the purposes of sorting.

Important note: The sorting syntax for the search_videos method is different from the sorting syntax for the other Media API read methods. The search_videos method uses a sort_by argument that includes the sort order, ascending or descending, as in the examples above. Several of the other Media API read methods that return multiple videos use instead a separate sort_by argument and sort_order argument, as in this example:

http://api.brightcove.com/services/library?command=find_all_videos&sort_by=plays_total&sort_order=DESC&token=[token]

Output format

As with all Media API read methods, the search_videos method has an optional output argument. By default, results from search_videos are in JSON format. By setting output=mrss, you can instead get the results in MRSS format, which you can then publish as a feed. Read more about RSS output from the Media API.

search_videos examples

Each of the following examples use a placeholder for the Media API token. To use these examples, substitute the Media API read token for your own Video Cloud account.

Finding videos using the "all" search parameter

Suppose you want to find all videos that have "football" and "Chicago" in the name, short description, or long description, and which also have the tag "free":

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=football&all=chicago&all=tag:free

Finding videos using the "any" search parameter

To limit the previous search to videos that also have either the tag "color" or the tag "technicolor":

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=football&all=chicago&all=tag:free&any=tag:color&any=tag:technicolor

Excluding search terms

To omit any videos that are tagged "black_and_white":

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=football&all=chicago&all=tag:free&none=tag:black_and_white

Searching in custom fields

Suppose videos in your account have a custom field named "season", which is an enum with the possible values: "Fall 2009", "Winter 2009", "Winter 2010", or "Spring 2010". To search for videos form the Fall 2009 season:

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=football&all=chicago&all=tag:free&all=season:Fall+2009&exact=true

To search for videos from either season of 2009:

http://api.brightcove.com/services/library?command=search_videos&token=1234.
    &all=football&all=chicago&all=tag:free&all=season:2009