Search and suggestions

Search is often the entry point to a project: find public resources first, then use their IDs with the more detailed video and channel methods.

Run a basic search

const page = await yt.search('learn typescript');

page.results[0].title; // 'TypeScript in 100 Seconds'
page.results[0].url; // 'https://www.youtube.com/watch?v=zQnBQ4tB3ZA'

for (const result of page.results) {
  console.log(result.title, result.url);
}

A page can contain videos, channels, and playlists. Fields shared by every result, such as title and url, can be read directly.

Narrow mixed result types

The type field tells TypeScript which shape you have:

for (const result of page.results) {
  if (result.type === 'video') {
    console.log(result.durationText, result.viewCount);
  } else if (result.type === 'channel') {
    console.log(result.handle, result.subscriberCountText);
  } else {
    console.log(result.videoCount);
  }
}

This check is called narrowing. It prevents code from asking a channel for a video-only property.

Add filters with a purpose

const page = await yt.search('learn typescript', {
  type: 'video',
  uploadDate: 'month',
  duration: 'medium',
  sortBy: 'view_count',
  features: ['hd', 'subtitles'],
  limit: 25,
});

page.results.length; // at most 25 — narrow filters often return far fewer
page.results[0].type; // 'video'

Option	Question it answers
`type`	Do you want videos, channels, playlists, movies, or shorts?
`uploadDate`	How recently should it have been uploaded?
`duration`	Should videos be short, medium, or long?
`sortBy`	Should relevance, rating, upload date, or view count lead?
`features`	Must results have subtitles, HD, live, 4K, HDR, or another feature?
`limit`	Roughly how many results should the SDK collect?

YouTube may occasionally include an unexpected renderer even with a type filter, so still check result.type before reading type-specific properties.

Autocomplete a partial query

Suggestions are simple strings:

const suggestions = await yt.suggestions('type scr');
// → ['typescript', 'typescript tutorial', 'typescript basics', …]

for (const suggestion of suggestions) {
  console.log(suggestion);
}

They use the client’s language and location. See locale and region when suggestions or search results should reflect a particular audience.