Search

Search

Methods

constructor

const search = ytcog.Search(session, searchOptions);

session is an instance of a ytcog.Session
searchOptions is a user defined object explained below

fetch

fetch() initiates the collection of metadata/results. fetch() provides the opportunity to change search options prior to execution. fetch() will continue to fetch results until it matches or exceeds the desired quantity of results or there are no more results to collect.

search.fetch([searchOptions]);

continued

continued() must be preceded by a fetch() method. continued() will fetch extra results. It can be called repeatedly.

search.continued();

Properties

Search objects can have the following properties.

search.status       (string) The result of the last fetch(), continued() or download() operations: Either OK,NOK or ERROR
search.reason       (string) The reason for status NOK or ERROR.
search.updated      (number) Timestamp of last fetch.
search.data         (string) or [(string)] The raw YouTube data fetched.
search.transferred  (number) Cumulative number of bytes of incoming data (compressed with gzip library). 
search.debugOn      (boolean) default is false. Set to true to get error information in the console. 
search.estimated    (number) The estimated number of results that meet your search criteria.
search.results      ([Item]) Array of objects fetched by the last fetch()/continued() cycle. 
search.videos       ([Video]) Accumulated array of video objects found so far.
search.playlists    ([Playlist]) Accumulated array of playlist objects found so far.
search.channels     ([Channel]) Accumulated array of channel objects found so far.
search.quantity     (number) The number of results collected by the last fetch()/continued() cycle. 
search.page         (number) Last page number of raw data collected on the last fetch()/continued() cycle. 

Options

searchOptions is an object with the following properties:

Required:

query:         (string) your search term.  

Optional:

order:         (string) the order in which YouTube delivers results:  
                * relevance             most relevant to the search term (default)
                * age                   newest to oldest
                * views                 most views
                * rating                highest rating

period:        (string) the focus period of the search: 
                * hour                  the past hour
                * day                   the past 24 hours (default)  
                * week                  the past week
                * month                 the past month
                * year                  the past year 
                * any                   any time

items:         (string) what will be searched for:  
                * any                   results may contain videos, playlists or channels
                * videos                results must contain videos only (default)
                * channels              results must contain channels only
                * playlists             results must contain playlists only
                * movies                result must contain movies (feature length videos) only

duration:      (string) the length of returned videos:  
                * any                   any length of video (default)
                * short                 less than 4 minutes long
                * medium                from 4 to 20 minutes long
                * long                  longer than 20 minutes

features:      (string) additional features. Add one or more of the following in a comma separated  
               string:
                * live                  live videos only
                * 4k                    4K resolution only
                * hd                    high definition only 
                * subtitles             videos with subtitles/close captions
                * cc                    licensed under creative commons  
                * 360                   360 degree videos only
                * vr180                 Virtual Reality 180 videos only
                * 3d                    3 dimensional videos only
                * hdr                   Videos with High dynamic range only
                * location              Videos with geo-location
                * purchased             Videos you have purchased
               By default no features are selected.

quantity:      (number) the desired number of results. If available the actual number of results will  
               match or exceed this number (default: 100).    

Examples:

Fetch 100+ short hd videos from the past month of dogs and mice - or cats and mice - but neither goofy, tom, jerry nor mickey

{
    query: "( dogs | cats ) & mice -jerry -tom -mickey -goofy",
    order: "relevance",
    period: "month",
    items: "videos",
    duration: "short",
    features: "hd",
    quantity: 100
}

Fetch 50+ most viewed playlists featuring Russell Brand

{
    query: "Russell Brand",
    order: "views",
    items: "playlists",
    quantity: 50
}

Fetch 20+ film review channels

{
    query: "film reviews",
    items: "channels",
    quantity: 20
}

NB: Period, Duration and Features relate only to video items. You should ensure the defaults: period: 'any', duration: 'any' and features: '' for channel and playlist searches.

Tip: An excellent resource for YouTube search operators: 50+ advanced YouTube search operators