WARNING: This API has been deprecated and should not be used for new projects. Click here for more information.

Using search_videos

search_videos is the most powerful and versatile of the video read methods, and the one you should be using in most cases.

Note: URLs for videos and images are subject to change without notice, so you need to pull them dynamically using the Media API when you use them in pages, or if that is not possible, re-run your queries to retrieve them regularly — every six hours is recommended — and update links in your pages as needed.

Getting all videos

To return all videos in the account, simply omit any search terms. You can still, or course, sort the results, specify what video fields are returned, and so forth.

Note: videos that are deactivated, or have been scheduled for a later date/time, will not be returned. These can be returned by using the find_modified_videos method, or one of the _unfiltered methods.

The call below returns all active videos — the video_fields and page_size are used to keep to limit the size of the returned data:


  //api.brightcove.com/services/library?command=search_videos&page_size=3
  &video_fields=id,name,shortDescription&page_number=0&get_item_count=true
  &token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..

Here is the data returned by the call:

Search terms

You can enter all, any, or none search terms:

  • all: returns videos that have all of the specified field values
  • any: returns videos that have any of the specified field values
  • none: returns videos that have none of the specified field values

If you only use a single search term, any and all will return exactly the same results. However, if you are searching on one term, try to future-proof your application by anticipating: if you were to add another term, would you want to find videos that matched both values or either value.

You can use these terms in any combination, so for example, if you wanted to return all videos that had the term "bird" in the title or short description, but exclude any videos tagged "private," the request would look like this:

Note: if your search term contains a : character, whatever precedes the ":" will be interpreted as a field name. So if you want to search for a term like "my:term", you will need to preface it with the field name you want to search: all=tag:my:term.

Also note that if you do not include a field (e.g. all=fish), the name, short description, and tags will be searched.


//api.brightcove.com/services/library?command=search_videos&any=bird&none=tag:private
&video_fields=id,name,shortDescription&page_number=0&get_item_count=true
&token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..

Search specific field

One of the most powerful features of search_videos is that you specify particular video fields to search for your terms in. You can see this in the previous example, where only the video tags are searched for the term "private". You can specify other video fields as well, such as the display_name and custom_fields (for more detail on searching custom fields, see the next section).

Field Name in search_videos Command Property Name in Video Object
display_name name
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.

Note: the fields you can search on include reference_id:


          //api.brightcove.com/services/library?command=search_videos
          &any=reference_id:1939487640001&page_size=3
          &video_fields=id,name,shortDescription&page_number=0
          &get_item_count=true&token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..
          

You can not search on the id field — to find videos by id, you will need to use one of the find_video(s)_by_id(s) methods.

Search custom fields

You can search on all custom fields, or on specific custom fields by the internal name:


// search on all custom fields
//api.brightcove.com/services/library?command=search_videos
&any=custom_fields:sea&video_fields=id,name,shortDescription&get_item_count=true
&token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..

// search a specific custom field called "producer"
// api.brightcove.com/services/library?command=search_videos
&any=producer:birdworld&video_fields=id,name,shortDescription&get_item_count=true
&token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..

Note: there are some reserved words that must not be used as custom field internal names (the display name does not matter). The only one you are likely to bump into is category. If you use category as the internal name for a custom field, searches on that field will return no results. If you already have a custom field named category, please replace it, using a field with a different name. If you wish to delete the category field, submit a request to Support — but the field will do no harm as long as you are not using it.

Specifying the field value you want to match works the same, whether the field is a list-type or text-type:


// topic is a list field with 3 values: air,sea,land
//api.brightcove.com/services/library?command=search_videos
&any=topic:air&any=topic:land&video_fields=id,name,shortDescription
&get_item_count=true&token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..

// producer is a text field, and I know that some values used are animalworld and birdworld
//api.brightcove.com/services/library?command=search_videos&
any=producer:birdworld&any=producer:animalworld
&video_fields=id,name,shortDescription&get_item_count=true
&token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..

Multiple search terms

One of the most commonly misunderstood aspects of search_videos is how you search on multiple terms. Say, for instance, that you want to return videos that have all of the following tags: bird; air; nature. To do this, you must include a separate all parameter for each search term, like this:


//api.brightcove.com/services/library?command=search_videos
&all=tag:bird&all=tag:air&all=tag:nature
&video_fields=id,name,shortDescription&get_item_count=true
&token=ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQun0xEEXtlDUHBDPZBCOzbw..

This is true for all, any, and none search terms.

Note: that a request including multiple terms like this — any=fish,bird,sea — is a valid request, but will not return the videos you want.

Sorting results

search_videos differs from the various find_ methods in that there is no sort_order parameter to specify ascending or descending order. Instead, this is specified in the value of the sort_by parameter: sort_by=CREATION_DATE:ASC or sort_by=CREATION_DATE:DESC. The default for sort order is ASC.