CMS API: Video Search v2

This topic explains the syntax for using version 2 of video search, supported by the CMS API.

Introduction

Version 2 of the video search used by the CMS API simplifies the syntax and makes it simpler to use. To see Version 1, go to CMS/Playback API: Videos Search v1.

Choosing which syntax to use is a simple matter of choosing the appropriate URL parameter:

  • To use the new v2 search: 
        .../videos?query={search_string}
  • To use the original search: 
        .../videos?q={search_string}

Basics

The basic element of a search string is a search term, which may be prefixed by a field name. If the field name is included, only that metadata field will be searched. Otherwise, several fields (listed below) will be searched.

For example:

Basic Search
Search string What will be returned
bird Videos that that the word "bird" in the fields listed below
name:bird Videos that have the word "bird" in the name (title) will be returned.

When you provide no field name to search, the request will search for that value in the following fields:

  • id
  • 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. text:bird)
  • tags
  • reference_id
  • custom_fields (searches all custom fields)
  • custom_field_name (searches a specific named custom field)
  • variants

The supported fields to search 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)
reference_id string or quoted string
clip_source_video_id string
clip_source_video_id:video_id
state ACTIVE, INACTIVE, PENDING, DELETED (only videos deleted within the past 10 days will be returned)
updated_at datetime or range (details below)
created_at datetime or range (details below)
schedule.starts_at datetime or range (details below)
schedule.ends_at datetime or range (details below)
published_at datetime or range (details below)
complete true or false
ad_keys quoted strings
ad_keys:"sport=swimming&category=aquatics"
economics string
economics:AD_SUPPORTED
economics:FREE
original_filename string or quoted strings
original_filename:oystercatcher.mp4
projection string
projection:equirectangular
cue_points string
has_cue_points:true
has_cue_points:false
geo string or quoted strings
geo.{property}:{value}
geo.countries:fr
images string
has_images:true
has_images:false
link string
has_link:true
has_link:false
sharing string or quoted string
sharing.{property}:{value}
sharing.by_external_acct:true
sharing.source_id:"parent_video_id"
sharing.by_id:"shared_from_account_id"
sharing.to_external_acct:"shared_to_account_id"
variants string or quoted string
variants.{language}.{property}:{value}
variants.en-US.name:eng
labels quoted string
labels:"/root/level1"
delivery_type string
delivery_type:dynamic_origin
delivery_type:live_origin
folder_id string
folder_id:6633bce70a73585a5816b82a
playback_rights_id string or quoted string
playback_rights_id:635011821
ingestion_profile_id string
ingestion_profile_id:583efe11e4b0a3fb4b6f0b1e
has_digital_master string
has_digital_master:true
has_digital_master:false
has_transcripts string
has_transcripts:true
has_transcripts:false
has_text_tracks string
has_text_tracks:true
has_text_tracks:false
drm_disabled string
drm_disabled:true
drm_disabled:false
offline_enabled string
offline_enabled:true
offline_enabled:false
created_by string
created_by.{property}:{value}
created_by.type:user
updated_by string
updated_by.{property}:{value}
updated_by.type:user
duration datetime or range (details below)
duration:[* TO 1450000]
plays_total range (details below)
plays_total:[0 TO 100000]
plays_trailing_week range (details below)
plays_trailing_week:[0 TO 100000]
shared_at date or range (details below)
shared_at:[2023-11-02T16:21:34.905Z TO 2024-05-02T16:21:34.908Z]

In both the examples shown above, videos that do not have the word "bird" in any relevant field might still be returned. The next section explains how to limit search results to only videos that have the specified terms.

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"

In addition, non-alphanumeric characters such as hyphens, underscores, line-breaks, "$", "&", "*", etc. are treated as word delimiters. For example, a search string like small-town will be treated as small town.

What is stemming?

Video fields that support stemming return words that have the stem of the search word in common. In addition, stemming supports entering whole words only, not partial words:

  • Example 1: Searching on running will return results containing: running, run, runs
  • Example 2: Searching on vid will not return results containing: video

Search with stemming works in the following fields:

  • custom_fields
  • description
  • name
  • long_description
  • tags
  • labels

There are some modifiers that help you limit search results to exactly the videos you want.

Search Modifiers
Modifier Description Examples
+ Prefixing a search term with the plus (+) sign signifies that the returned videos must have the specified term
  • +bird (returns only videos with "bird" in the fields listed above)
  • +tags:bird (returns only videos with "bird" in the tags)
- or NOT Prefixing a search term with the minus (-) sign or NOT signifies that the returned videos must not have the specified term
  • -birds or NOT birds (returns only videos that do not have "bird" in the fields listed above)
  • -name:birds or NOT name:birds (returns only videos that do not have "bird" in the name)
(term) AND (term)
or
(term) OR (term) 		The logical AND and OR operators allow you to combine multiple search terms for complex queries
  • (economics:FREE) AND (has_text_tracks:true) (would return videos that have both "FREE" in economics and has_text_tracks)
  • (original_filename:oystercatcher.mp4) OR (duration:[* TO 14500]) (would return videos that have either "oystercatcher.mp4" in the original_filename and duration up to 14500 seconds)
  • (variants.en-US.name:"My Variant") AND (has_images:true) AND (NOT labels:"/root/label5") (would return videos that have both "My Variant" in the Variant name and has images, but not the label "/root/label5")

Phrase search

You can search for a phrase (rather than a single word) by placing in quotation marks:

  • "blue heron"
  • name:"blue heron"

Date/Times and Ranges

Search on a date-time interval by using:

[{start} TO {end}]

To search on a single date/time, set the start and end to the same value:

[2019-09-30T00:00:00.000Z TO 2019-09-30T00:00:00.000Z]

Date-time values are specified using the ISO 8601 format:

Date/Time Formats
Date-Time Format Example
Date-Time yyyy-MM-ddThh:mm:ss.sssZ 2019-09-30T14:24:33.512Z
Wildcard (can be used for the start or end date/time and ranges) *
  • 2019-09-30T14:24:33.512Z TO *
  • * TO 2019-09-30T14:24:33.512-4:00Z
  • [500 TO *]
  • [* TO 340000]

Below are some sample date/time search strings.

Sample Data/Time Searches
Search String Description
+updated_at:[2019-09-30T00:00:00.000Z TO 2019-10-07T00:00:00.000Z] Videos updated between 30 Sep 2019 and 7 Oct 2019
+created_at:[2019-09-30T00:00:00.000Z TO 2019-09-30T00:00:00.000Z] Videos added on 30 Sep 2019
+created_at:[2019-09-30T14:00:00.000Z TO 2019-09-30T16:30:00.000Z] Videos added between 2:00PM and 4:30PM (UTC) on 30 Sep 2019
+created_at:[* TO 2019-09-30T00:00:00.000Z] Videos added before 30 Sep 2019

clip_source_video_id

The clip_source_video_id field identifies the original source video from which a clip was created.

When a clip is generated from a live job (for example, via the Brightcove Studio Live module), the resulting clip includes a metadata property called clip_source_video_id. This property stores the video ID of the original live job that the clip was derived from.

This field can be used in CMS API search queries to retrieve all clips created from a specific live video. For instance, when viewing a live job in Brightcove Studio and opening the Saved Clips list, the Studio interface calls the Get Videos API with a query that filters by clip_source_video_id, returning all clips associated with that live job.

Example Query

GET https://cms.api.brightcove.com/v1/accounts/{account_id}/counts/videos?query=+clip_source_video_id:{source_video_id}

Use Cases

  • Retrieve all clips generated from a particular live job or source video.
  • Organise and manage clips programmatically using the CMS API.

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.

For general search instructions in Video Cloud, see Media Module Search.