Search for Videos

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.

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

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=namemy%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".

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"

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

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 - (%2D) sign immediately preceding the term.

Required/Excluded Terms
example urlencoded 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 %2Dfoo videos must NOT include the term 'foo' in the name, description, long_description, tags, reference_id or custom fields
-name:foo %2Dname: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=%2Dtags: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 an exact match, or match multiple words, just wrap the term in quotes:

q="foo"
q="foo bar"

This also works when searching against a specific field:

q="foo"
q=name:"foo bar"
  • Exact match

    Example: This request returns videos which matches exactly a value of sea in the tags field.

    https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:"sea"
  • 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, this request returns only those videos which have a value of sea,mammal in the tags field.

    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: Custom fields are treated as strings.

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.

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 (%2D1d) 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 alway 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:%2D1day videos updated from 1 day ago to the current day
q=created_at:-2days q=created_at:%2D2days videos added from 2 days ago to the current day
q=updated_at:-4hours q=updated_at:%2D4hours video updated from 4 hours ago to the current time
q=created_at:-60minutes q=created_at:%2D60minutes videos added from 60 minutes ago to the current time
q=created_at:2016-01-01&to=-1d q=created_at:2016-01-01&to=%2D1d videos created from January 1, 2015 to yesterday
q=updated_at:-14d.. q=updated_at:%2D2d.. 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:%2D2days..

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=%2Dschedule.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=%2Dschedule.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 paramater:

q=state:ACTIVE( | INACTIVE | PENDING)

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=%2Dis_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 decending 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+%2Dtags: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+bar returned items have "foo" OR "bar" (identical to the search above)
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=%2Bfoo+%2Bbar returned item must have "foo" AND "bar"
q=-foo +bar q=%2Dfoo+%2Bbar returned item must have "bar" AND not have "foo"