support Contact Support | system status System Status
Page Contents

    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)

    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.

    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

    Page last updated on 29 Sep 2020