In this topic, you will learn how to do the following:
- Create and limit a basic search using the
- 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
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
For example, to search for "my favorite video" in the name:
+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
- Some agents may not handle literal quotation marks correctly, so it is safer to encode
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 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".
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
offset. All URL parameters are separated by
&, and the order does not matter.
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:
To perform a search of terms in your media library, use the
The search terms that you specify should be a url encoded list of terms separated by a space.
When you provide no qualifier for a search term, such as
q=bird, the request will search for that value in the following fields:
custom_fields(searches all custom fields)
custom_field_name(searches a specific named custom field)
q=id:12345will return exactly the same results as the request
Example: This request returns videos which have a value of bird in at least one of the fields listed above.
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
The supported search fields are:
|name||strings or quoted strings|
|text||strings or quoted strings (name, description, 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|
|complete[2-2]||true or false|
- [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
completeproperty is automatically set to
false. As soon as one rendition exists for the video, the
completeproperty will be automatically set to
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.
|+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
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
- Multiple words
Example: Notice that this request returns videos which have either a value of sea or mammal in the
But, this request returns only those videos which have a value of sea,mammal in the
You may search on any custom field that you have defined for your videos.
Note: Custom fields are treated as strings.
Example: This request returns videos which have a value of animal in the
subject custom field.
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.
Supported date formats
The supported date formats include UTC and relative.
|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)|
For relative dates we support a direction (
-) followed by a number, followed by a duration. Relative dates are alway measured from the current time. Legal durations are: minutes, hours, days.
|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
Example: Search for all videos modified after August 11, 2013:
NOW operator for schedule dates
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:
|?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.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
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
|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"|