ytsearcher

A nodejs package that provides an easy-to-use promise-based system of getting youtube search results

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
ytsearcher
1931.2.43 years ago6 years agoMinified + gzip package size for ytsearcher in KB

Readme

<br />
<p>
    <a href="https://www.codacy.com/app/wzhouwzhou/ytsearcher?utm_source=github.com&utm_medium=referral&utm_content=wzhouwzhou/ytsearcher&utm_campaign=Badge_Grade"><img src="https://api.codacy.com/project/badge/Grade/1c131140d5974a798c4c2509df7bd452" alt="Codacy Badge" /></a>
    <a href="https://www.npmjs.com/package/ytsearcher"><img src="https://img.shields.io/npm/v/ytsearcher.svg" alt="NPM version" /></a>
    <a href="https://www.npmjs.com/package/ytsearcher"><img src="https://img.shields.io/npm/dt/ytsearcher.svg" alt="NPM downloads" /></a>
    <a href="https://david-dm.org/wzhouwzhou/ytsearcher"><img src="https://img.shields.io/david/wzhouwzhou/ytsearcher.svg" alt="Dependencies" /></a>
    <a href="https://snyk.io/test/npm/ytsearcher"><img src="https://snyk.io/test/npm/ytsearcher/badge.svg" alt="Known Vulnerabilities" data-canonical-src="https://snyk.io/test/npm/ytsearcher" style="max-width:100%;"></a>
    <a href="https://bundlephobia.com/result?p=ytsearcher"><img src="https://badgen.net/bundlephobia/minzip/ytsearcher" alt="BundlePhobia" /></a>
    <a href="https://paypal.me/wzhouwzhou"><img src="https://img.shields.io/badge/donate-paypal-009cde.svg" alt="Paypal" /></a>
</p>
<p>
    <a href="https://nodei.co/npm/ytsearcher/"><img src="https://nodei.co/npm/ytsearcher.png?stars=true&downloads=true"></a>
</p>
YTSearcher

A nodejs package that provides an easy-to-use promise-based system of getting youtube search results.

Installing via NPM.

``$ npm i ytsearcher@latest``

Why ytsearcher?

• Modern and trustworthy (typings(!), promises, es6, up-to-date) with thousands of downloads.
• Lightweight (minified + gzip ~2.5kB) and NO other dependencies; this means more productivity, less bloat!

I'm all about that! How do I start searching YouTube the right way?

Creating the object:
const { YTSearcher } = require('ytsearcher');
const searcher = new YTSearcher(apikey);
Notice the { } around YTSearcher. That is intentional!
It's a good idea to get a key due to Google's rate limit on the API. For details on how to obtain an API key and create a project visit this link
By default the api key will be irretrievable. This should be fine for most situations. To enable access to searcher.key create the object like so:
const searcher2 = new YTSearcher({
  key: apiKey,
  revealkey: true,
});
To Perform Searches
This package interacts directly with google's api. The base url can be retrieved by doing ``const { apiurl } = require('ytsearcher');``
// result will be a YTSearch object.
let resultA = await searcher.search('A Search Query');

// You can customize your search with like so:
let resultB = await searcher.search('Another Query', searchOptions)
A list of options is available here
Or you can fetch the list via: ``const { validOptions } = require('ytsearcher');`` which will return the array.
Examples
// For example, to grab only video results from a search query:
let resultC = await searcher.search('A Third Query', { type: 'video' });

// This shortcut will log the first search result (in the active page).
console.log(result.first);

// This will log the url of the first search result (in the active page).
console.log(result.first.url);

Pagination

A YTSearch has a built in page flipper, which will update the properties of YTSearch, including search.first.
// These will return null when the last and first page have been hit (respectively).
await result.nextPage();
await result.prevPage();

// result.currentPage is an array of objects containing the current active page in the search object.
const currentPage = result.currentPage

// To print everything in the current page.
console.log(currentPage);

// You can also get individual elements from it like so:
console.log(currentPage.first());
console.log(currentPage.last());
console.log(currentPage[1]);

Summary example to get the url of the second result on the second page of a video-only search (assuming both the page and the result exist):

For async functions:
(async () => {

const APIKEY = "12345"; // replace me
const QUERY = "Anything you want"; // replace me too

const { YTSearcher } = require('ytsearcher');
const ytsearcher = new YTSearcher(APIKEY);

// Type can be 'all', 'video', 'channel', 'playlist', or comma separated combination such as 'video,channel'
const searchResult = await ytsearcher.search(QUERY, { type: 'video' });

const secondPage = await searchResult.nextPage();
// secondPage is same object as searchResult

const page = secondPage.currentPage;
const videoEntry = page[1];

console.log(videoEntry.url);

})();
For completely non-async functions:
const APIKEY = "12345"; // replace me
const QUERY = "Anything you want"; // replace me too

const { YTSearcher } = require('ytsearcher');
const ytsearcher = new YTSearcher(APIKEY);

ytsearcher.search(QUERY, { type: 'video' })
.then(searchResult => {

  searchResult.nextPage()
  .then(secondPage => {
    // secondPage is same object as searchResult

    const page = secondPage.currentPage;
    const videoEntry = page[1];

    console.log(videoEntry.url);
  });
});
The Search Query can be anything, including a youtube link itself.
Searches may error, and if an error code is available it will be in the error. A list of possible errors responses is available here: https://developers.google.com/analytics/devguides/reporting/core/v3/errors
Version:
const version = require('ytsearcher').version;
Full docs are available here: http://ytsearcher.willyz.cf
Enjoy this package? Consider starring on github and checking out some of my other work:
Fluent Filepaths
Urban Dictionary
Need support? Send me an email at wzhouwzhou@gmail.com, or connect with me on Discord at https://discord.gg/jj5FzF7 (William Zhou#0001)
Like what you're seeing? Consider helping to fund my education through https://paypal.me/wzhouwzhou