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.

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

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
  • (+name:heron) AND (+tags:bird) (would return videos that have both "heron" in the name and "bird" in the tags)
  • (+name:heron) OR (+tags:bird) (would return videos that have either "heron" in the name and "bird" in the tags)
  • ((+name:heron) AND (+tags:bird)) AND (NOT tags:internal) (would return videos that have both "heron" in the name and "bird" in the tags, but not the tag "internal")

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

You can 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) *
  • 2019-09-30T14:24:33.512Z TO *
  • * TO 2019-09-30T14:24:33.512-4:00Z

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

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.