CMS/Playback API: Videos Search

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Get Video Metadata
Topic(s)
Searching
API(s)
CMS API

In this topic, you will learn how to search for videos in your account using the CMS API. Brightcove's CMS API provides a programmatic way to search for videos in your Video Cloud library. This topic provides detail on the search syntax. Note that this topic covers video search - also see Playlist Search.

Introduction

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

  • Create and limit a basic search using the q parameter
  • 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.

Sorting of search results

For search queries that return a large number of results, the sorting of the results is based on a complex relevance algorithm.

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.

Spaces/Special Characters

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

  • Spaces are not allowed, and can be replaced either with + signs or %20

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

    q=name:my+favorite+video

    or

    q=name:my%20favorite%20video

  • Since + signs are interpreted as word separators, 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:

    q=name:two%2Btwo

    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.

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".

Combined with other params

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

Examples

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

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

Search specific videos

If you want to limit your search to a specific set of videos, you can do so by including the ids as part of the search:

q=id:123456789+id:987654321+id:48376387+tags:foo

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"

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)

Notes

[1-1] Note: searching by id is included for consistency, but a search on q=id:12345 will return exactly the same results as the request https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/12345

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:

Supported Search Fields
Field Legal values
name strings or quoted strings
text strings or quoted strings (searches the name, description, and long_description)
tags strings or quoted strings (multiple tags should be comma-delimited)
custom_fields strings or quoted strings (searches all custom fields - you can also use a specific custom field internal name) [2-1]
reference_id string or quoted string
state ACTIVE, INACTIVE, PENDING, DELETED [2-3]
updated_at date range
created_at date range
schedule.starts_at date range
schedule.ends_at date range
published_at date range
complete [2-2] true or false

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

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.

Note that because of the potential confusion between "+" as an indicator of a space or a required term, you must encode it as %2B when using it to indicated a required term.

Required/Excluded Terms
example url-encoded meaning
+foo %2Bfoo videos MUST include the term foo in the name, description, long_description, tags, reference_id or custom_fields
+custom_fields:foo %2Bcustom_fields:foo video MUST include the value foo for some custom field
-foo -foo videos must NOT include the term foo in the name, description, long_description, tags, reference_id or custom_fields
-name:foo -name:foo videos must NOT include the term foo in the name

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

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

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

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+bar"or q=%22foo+bar%22

This also works when searching against a specific field:

q=name:"foo"
q=name:name:"foo+bar"

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 videes 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-08T00:00:00Z

Supported date formats

The supported date formats include UTC and relative.

Date Format Examples
format (URI-encoded format) meaning
2015-08-01T06:15:00Z This represents a time in UTC.
2012-08-01 This represents midnight on a day in UTC. The example is equivalent to 2012-08-01T00:00:00Z
-1d (-1d) The current time minus 1 day. (see below)

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:

Relative Date Samples
q param for dates URI-encoded Meaning
q=updated_at:-1day.. q=updated_at:-1day.. videos updated from 1 day ago to the current day
q=created_at:-2days q=created_at:-2days videos added 2 days ago
q=updated_at:-4hours.. q=updated_at:-4hours.. video updated from 4 hours ago to the current time
q=created_at:-60minutes.. q=created_at:-60minutes.. videos added from 60 minutes ago to the current time
q=created_at:2016-01-01&amp..-1d q=created_at:2016-01-01&amp..-1d videos created from January 1, 2015 to one day ago
q=updated_at:-14d.. q=updated_at:-14d.. videos in the past two weeks

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 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 only, 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. One of its key advantages is that it will include results for videos that have no explicit schedule set. A couple of examples:

Schedule Data Examples
from/to params URI-encoded Meaning
?q=schedule.starts_at:..NOW ?q=schedule.starts_at:..NOW starts_at is from the beginning of time to this moment
?q=schedule.ends_at:NOW.. ?q=schedule.ends_at:NOW.. ends_at is from this moment to the end of time
?q=-schedule.starts_at:NOW.. ?q=-schedule.starts_at:NOW.. starts_at is NOT between this moment and the end of time (equivalent to starts_at is before this moment)
?q=-schedule.ends_at:NOW.. ?q=-schedule.ends_at:NOW..  
?q=+schedule.starts_at:..NOW+schedule.ends_at:NOW.. ?q=%2Bschedule.starts_at:..NOW+%2Bschedule.ends_at:NOW.. starts_at before this moment and ends_at after this moment (video is in schedule this moment)

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).

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=-is_clip:true - returns only non-clips
  • q=%2Bis_clip:false - returns only non-clips (functionally identical to the previous item)
  • q=%2Bclip_source_video_id: video_id - returns clips generated from the specified video

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+%2Bupdated_at:2010-08-01T00:00:00Z..2010-10-08T00:00:00Z&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%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+%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+-tags:bar

Examples

Samples: Combining Terms
Unencoded search string URI-encoded search string Meaning
q=foo bar q=foo+bar returned items have "foo" OR "bar"
q=foo +bar q=foo+%2Bbar returned items must have "bar", may have "foo"
q=+foo bar q =%2Bfoo+bar returned items must have "foo", may have "bar"
q=+foo +bar q=%2Bfooc+%2Bbar returned item must have "foo" AND "bar"
q=-foo +bar q=-foo+%2Bbar returned item must have "bar" AND not have "foo"
Multiple tag searches
q=tags:bee,bop q=tags:bee,bop returns videos with tag "bee" OR "bop"
q=tags:bee+tags:bop q=tags:bee+tags:bop returns videos with tag "bee" OR "bop"
q=+tags:bee+tags:bop q=%2Btags:bee+tags:bop all videos returned must have tag "bee"; they may have tag "bop" as well
q=+tags:bee++tags:bop q=%2Btags:bee+%2Btags:bop all videos returned will have tag "bee" AND tag "bop"