CMS/Playback API: Videos Search v1

Introduction

In this topic, you will learn how to do the following:

• Create and limit a basic search using the q parameter
• Sort search results
• Search using required and excluded terms
• Use a quoted search to match exact terms and multiple words
• Search on custom fields
• Search date fields with a specific date and with ranges
• Combine search criteria

API usage

The search functionality can be used with either the CMS API or the Playback API.

CMS API

When using search with the CMS API, the following apply:

• All requests (including search) require an authorization header which contains your access tokens. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.
• There is no limit on the maximum number of videos returned from a search, but rate limiting does apply.
• Search results include all videos in your account, whether they are playable or not, and/or geo-restricted.

For API request/response details, see the Get Videos section of the CMS API Reference.

Playback API

When using search with the Playback API, the following apply:

• Search requests with the Playback API require a Policy Key that is search-enabled.
• There is a limit on the maximum number of videos returned from a search.
• Search results will only return videos that are playable (videos with state:inactive will be ignored).
• Searches enforce playback policy restrictions, such as omitting geo-restricted videos from the results.
• Caching of results provide higher request rates and quicker responses, and there is no rate limiting.

For API request/response details, see the Get Videos section of the Playback API Reference.

Basic search

To perform a search of terms in your media library, use the q parameter.

      q={search terms}
    

The search terms that you specify should be a url encoded list of terms separated by a space.

Search supports stemming. Stemming is the mapping of a word to the word root and others words that stem from the same root. For example, a search on "run" should match videos that have "running" or "ran" in the specified field(s). It would not match "rune" because "rune" does not have "run" as its root.

When you provide no qualifier for a search term, such as q=bird, the request will search for that value in the following fields:

• id [1-1]
• name
• description
• long_description
• text (not a real metadata field, but a pseudo-field that you can use to search the name, description, and long_description - e.g. q=text:bird)
• tags
• reference_id
• custom_fields (searches all custom fields)
• custom_field_name (searches a specific named custom field)^[1-2]

Notes

        q=color:green%20color:blue
      

Example: This request returns videos which have a value of bird in at least one of the fields listed above.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=bird
      
    

Limit search to a specific property

When you provide a qualifier for a search term, such as q=name:bird, the request will search the video name field for a value of bird.

Example: This request returns videos which have a value of wildlife in the name field.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=name:wildlife
    

The supported search fields are:

Notes

• ^[2-1] It is not possible to search for videos that have a custom field that has no value or a value of null, because unless the field has been given a value, it is not included in the video metadata at all.
• ^[2-2] when you create a new video, the complete property is automatically set to false. As soon as one rendition exists for the video, the complete property will be automatically set to true.
• ^[2-3] The following limitations apply to searching for DELETED videos:
  • Search for deleted videos is only available using the CMS API; the Playback API will not return deleted videos
  • Only videos deleted during the previous 10 days (the current time minus 10 days) will be returned

Sorting of search results

The sort parameter allows you sort results of a get request for videos. You can sort on the following:

• reference_id
• name
• created_at
• published_at
• updated_at
• schedule.starts_at
• schedule.ends_at
• state
• plays_total
• plays_trailing_week

When not explicitly sorting results through the use of sort, results will be sorted according to an algorithm know as Term Frequency/Inverse Document Frequency or TF-IDF. See here for more information.

For example, let's say you search on the terms coastal,city and there are 120 videos in your account that have those terms somewhere in the video metadata ( name, description, tags, and so forth) and that also match the sorting criteria for the results (for example, they all have the same schedule_starts_at date/time). How high in the results a video appears is determined by the frequency that one or both terms appear in the metadata, with greater weight given to the term that appears most frequently in your video library as a whole.

Required/excluded terms

You can mark a search term as required (returned videos MUST match) or excluded (returned videos must NOT match). This is controlled with a URI-encoded + (%2B) or - sign immediately preceding the term.

You must encode + as %2B when using it to indicate a required term.

Example: This request returns videos which HAVE a value of sea but DO NOT have a value of lake in the tags field.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=%2Btags:sea%20-tags:lake
    

See Combining search criteria below to see how to use required/excluded syntax to enforce AND logic for multiple search terms.

Combined with other params

Search (using the q parameter) can be combined with other parameters such a sort, limit and offset. All URL parameters are separated by &. Parameter order does not matter.

Examples

Example: This request returns videos which must have a value of bar in the tag field and may have a name containing value foo

      .../videos?q=name:foo%20%2Btags:bar&sort=updated_at
    

Example: This request returns the same videos as above, but additionally sorts those results by the field updated_at and then limits the results to just 10 videos.

      .../videos?sort=updated_at&q=name:foo%20%2Btags:bar&limit=10
    

Quoted search terms

By default, a search will match similar words with your search terms. If you want to match multiple words, just wrap the term in quotes.

Most browsers and other agents will treat literal quotation marks ("...") correctly, but if you run into a case where quoted search terms do not appear to be returning correct results, try replacing the quotation marks with %22 (%22...%22)

      
        q="foo" or q=%22foo%22
        q="foo%20bar" or q=%22foo%20bar%22
      
    

This also works when searching against a specific field:

      
        q=name:"home"
        q=name:"home%20run"
      
    

Multiple words

Example: Notice that this request returns videos which have either a value of sea or mammal in the tags field.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:sea,mammal
    

But, the following request returns only those videos which have a tag sea,mammal.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:"sea,mammal"
    

Custom fields

You may search on any custom field that you have defined for your videos.

      q=my_field:foo
        q=my_field:"foo"
    

Note: all custom field values are treated as strings. For example, if you have a list-type custom field that can take the values true or false, search will look for those strings, not boolean values (in many programming languages, 1 and 0 can be used interchangeably with true and false as boolean values, but searching on q=my_boolean_field:1 will not return videos that have my_boolean_field set to true).

Example: This request returns videos which have a value of animal in the subject custom field.

      https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=subject:animal
    

Date ranges

If you are searching on a date field, you can specify a specific date or a range of dates, using two periods to separate the start and end dates (q=updated_at:2018-01-01..2018-02-01).

This will search for all videos with an updated_at value between Aug 1, 2012 and October 8, 2012. Here we are specifying each date in UTC format.

      q=updated_at:2012-08-01T00:00:00Z..2012-10-08T23:59:59Z
    

You can simplify this search by dropping the time components. The following is equivalent to the search above.

      q=updated_at:2012-08-01..2012-10-08
    

Supported date formats

The supported date formats include UTC and relative.

Relative dates

For relative dates we support a direction ( + or -) followed by a number, followed by a duration. Relative dates are always measured from the current time. Legal durations are: minutes, hours, days.

Examples:

Open ended ranges

If you want to match all dates until a given time, or match all dates since a given time, leave off one end of the range.

Example: Search for all videos modified in the last 2 days

      q=updated_at:-2days..
      
    

Example: Search for all videos modified on or after August 11, 2013:

      q=updated_at:2013-08-11T00:00:00Z..
      
    

NOW operator for schedule dates

For schedule.starts_at and schedule.ends_at, you can use NOW as a date value. This is a convenience operator that allows you to set up a dynamic query based on the current date-time. A couple of examples:

Combine search criteria

You can combine criteria for complex searches.

Example: This request searches for videos with a name value of gossip, which were updated between August 1, 2010 and October 8, 2010. It then sorts the response data by updated_at date in descending order.

      q=%2Bname:gossip%20%2Bupdated_at:2010-08-01..2010-10-08&sort=-updated_at
    

Combining terms

Use the required/excluded syntax to return videos that have all of the specified terms.

For example, if you search on:

      q=name:foo +tags:bar (URI-encoded: q=name:foo%20%2Btags:bar)
    

the response will contain videos that have the tag 'bar' and may also have foo in the name. If you want to return only those videos that have foo in the name AND the tag 'bar', you must search on:

      (unencoded) q=+name:foo +tags:bar
        (URI-encoded) q=%2Bname:foo%20%2Btags:bar
    

Similarly, if you want to return only videos that have foo in the name, but do not have the tag 'bar', you would search on:

      (unencoded) q=+name:foo -tags:bar
        (encoded) q=%2Bname:foo%20-tags:bar
    

Examples

Search specific videos

If you want to limit your search to a specific set of videos, you can do so searching on id:

Example: This request returns videos with ids 123456789, 987654321 and 48376387

      q=id:123456789%20id:987654321%20id:48376387
    

Search by state

You can perform or filter searches by the state of the video using the parameter:

      q=state:ACTIVE( | INACTIVE | PENDING | DELETED)[3]
    

Notes

• ^[3] Search for DELETED videos is only available for videos deleted in the past 10 days (the current time minus 10 days), and only through the CMS API (not the Playback API).

Stemming

Stemming is supported, but not partial word searches. For example, q=name:ban should return videos with the names "Parking Ban Announced" or "Parking to be Banned" or "City Banning Parking" but not "Bank Holiday" or "Bandit Captured".

Spaces/Special Characters

The CMS API generally handles special characters in search strings, with a couple of exceptions:

• Spaces are not allowed, and must be encoded as %20. (Unencoded + signs can also replace spaces, but this can lead to confusion in your queries as + can also indicate that a term is required. See required/excluded syntax)

  For example, to search for "my favorite video" in the name:

  q=name:"my%20favorite%20video"

• To search for a literal + sign or to use the + to indicate that the returned videos must include a term, you must encode the + as %2B:

  Searching for Videos that must contain "two+two" in the name field

  q=name:two%2Btwo

  Searching for Videos that must contain "heron" in the name field

  q=%2Bname:heron

• Some agents may not handle literal quotation marks correctly, so it is safer to encode "foo" as %22foo%22

For one-off requests, you can use Brightcove Learning's string encoder to encode your search strings. For apps, you'll need to find a URI encoding function in the language you are using.

Clip search terms

Clips are videos created from sections of other videos. Clips can be generated by Brightcove Social, and other means will be available in the future. There are some special search terms you can use to find generated clips in an account:

• q=%2Bis_clip:true - returns only clips
• q=%2Bis_clip:false - returns only non-clips
• q=%2Bclip_source_video_id:video_id - returns clips generated from the specified video

Ignored words

Certain words are ignored in search strings because they are so common that they are likely to return many results unrelated to what you are actually searching for. Below is a list of words that are ignored by search:

"a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"

Known issues

• Duplicate results: in certain cases, some items in the search results may appear more than once.

  Workaround: to prevent duplicate search results, always use a sort parameter in your search requests.