Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wzhouwzhou/ytsearcher
YTSearcher | 170k+ DL | 1000+ Dependents | NodeJS package providing an easy-to-use promise-based solution for getting youtube search results.
https://github.com/wzhouwzhou/ytsearcher
es6 google-api modern nodejs promise searcher youtube youtube-search ytsearcher
Last synced: 5 days ago
JSON representation
YTSearcher | 170k+ DL | 1000+ Dependents | NodeJS package providing an easy-to-use promise-based solution for getting youtube search results.
- Host: GitHub
- URL: https://github.com/wzhouwzhou/ytsearcher
- Owner: wzhouwzhou
- License: apache-2.0
- Created: 2017-07-10T21:22:44.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2021-03-31T03:34:23.000Z (over 3 years ago)
- Last Synced: 2024-09-19T03:02:25.169Z (14 days ago)
- Topics: es6, google-api, modern, nodejs, promise, searcher, youtube, youtube-search, ytsearcher
- Language: JavaScript
- Homepage: https://ytsearcher.willyz.cf
- Size: 465 KB
- Stars: 18
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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.2kB) 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:**
```js
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](https://developers.google.com/youtube/v3/getting-started)
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:
```js
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
```js
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](https://developers.google.com/youtube/v3/docs/search/list)
Or you can fetch the list via:
```js
const { validOptions } = require('ytsearcher');
```
which will return the array.
**Examples**
```js
// 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.**
```js
// 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:**
```js
(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:**
```js
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](https://developers.google.com/analytics/devguides/reporting/core/v3/errors)
Version:
```js
const version = require('ytsearcher').version;
```
Full docs are available here: [http://ytsearcher.willyz.cf](https://ytsearcher.willyz.cf)
Enjoy this package? Consider starring on [github](https://github.com/wzhouwzhou/ytsearcher) and checking out some of my other work:
[Fluent Filepaths](https://npmjs.com/easypathutil)
[Urban Dictionary](https://npmjs.com/easyurban)
Need support? Send me an email at [email protected], 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