# ytsr

> Simple package to search YouTube - no strings attached.

Latest version **3.8.4** (published 2023-08-11) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install ytsr
pnpm add ytsr
yarn add ytsr
bun add ytsr
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.8.4 |
| Published | 2023-08-11 |
| First published | 2017-03-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8 |
| Dependencies | 1 |
| Unpacked size | 45.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 281 |
| Author | Tobias Kutscha |
| Maintainers | timeforaninja |
| Keywords | youtube, search, yt, ytsearcher, api, playlist, channel, video, scrape, pagination, promise |

## Links

- npm: https://www.npmjs.com/package/ytsr
- Repository: https://github.com/TimeForANinja/node-ytsr
- Homepage: https://github.com/TimeForANinja/node-ytsr#readme
- Issues: https://github.com/TimeForANinja/node-ytsr/issues
- npm.io page: https://npm.io/package/ytsr

## Dependencies (1)

- [miniget](https://npm.io/package/miniget.md) ^4.2.2

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 3.8.4 (latest) — 2023-08-11
- 3.8.3 — 2023-08-11
- 3.8.2 — 2023-04-14
- 3.8.1 — 2023-03-29
- 3.8.0 — 2022-04-30
- 3.7.0 — 2022-04-11
- 3.6.0 — 2022-01-12
- 3.5.3 — 2021-08-13
- 3.5.2 — 2021-08-04
- 3.5.1 — 2021-08-04
- 3.5.0 — 2021-04-25
- 3.4.1 — 2021-04-10
- 3.4.0 — 2021-03-31
- 3.3.1 — 2021-02-15
- 3.3.0 — 2021-02-14
- … 39 more at https://npm.io/package/ytsr/versions

## README

# node-ytsr
[![NPM version](https://img.shields.io/npm/v/ytsr.svg?maxAge=3600)](https://www.npmjs.com/package/ytsr)
[![NPM downloads](https://img.shields.io/npm/dt/ytsr.svg?maxAge=3600)](https://www.npmjs.com/package/ytsr)
[![codecov](https://codecov.io/gh/timeforaninja/node-ytsr/branch/master/graph/badge.svg)](https://codecov.io/gh/timeforaninja/node-ytsr)
[![Known Vulnerabilities](https://snyk.io/test/github/timeforaninja/node-ytsr/badge.svg)](https://snyk.io/test/github/timeforaninja/node-ytsr)
[![Discord](https://img.shields.io/discord/484464227067887645.svg)](https://discord.gg/V3vSCs7)

Simple js only package to search for Youtube for Videos, Playlists and many more.
Does not require any login or Google-API-Key.

# Support
You can contact us for support on our [chat server](https://discord.gg/V3vSCs7)

# Usage

```js
const ytsr = require('ytsr');

const searchResults = await ytsr('github');
```


# API
### ytsr(searchString, [options])

Searches for the given string

* `searchString`
    * search string or url (from getFilters) to search from
* `options`
    * object with options
    * possible settings:
    * gl[String] -> 2-Digit Code of a Country, defaults to `US` - Allows for localisation of the request
    * hl[String] -> 2-Digit Code for a Language, defaults to `en` - Allows for localisation of the request
    * safeSearch[Boolean] -> pull items in youtube restriction mode.
    * limit[integer] -> limits the pulled items, defaults to 100, set to Infinity to get the whole list of search results - numbers <1 result in the default being used
    * pages[Number] -> limits the pulled pages, pages contain 20-30 items, set to Infinity to get the whole list of search results - numbers <1 result in the default limit being used - overwrites limit
    * requestOptions[Object] -> Additional parameters to passed to [miniget](https://github.com/fent/node-miniget), which is used to do the https requests

* returns a Promise
* [Example response](https://github.com/timeforaninja/node-ytsr/blob/master/example/example_search_output.txt)


### ytsr.getFilters(searchString, options)

Pulls avaible filters for the given string or link

#### Usage

```js
const ytsr = require('ytsr');

const filters1 = await ytsr.getFilters('github');
const filter1 = filters1.get('Type').get('Video');
const filters2 = await ytsr.getFilters(filter1.url);
const filter2 = filters2.get('Features').get('Live');
const options = {
  pages: 2,
}
const searchResults = await ytsr(filter2.url, options);
```

* `searchString`
    * string to search for
    * or previously optained filter ref
* `options`
    * gl[String] -> 2-Digit Code of a Country, defaults to `US` - Allows for localisation of the request
    * hl[String] -> 2-Digit Code for a Language, defaults to `en` - Allows for localisation of the request
    * requestOptions[Object] -> Additional parameters to passed to [miniget](https://github.com/fent/node-miniget), which is used to do the https requests
* returns a Promise resulting in a `Map<String, Map<String, Filter>>`
* [Example response](https://github.com/timeforaninja/node-ytsr/blob/master/example/example_filters_output.txt)

### ytsr.continueReq(continuationData)
Continues a previous request by pulling yet another page.  
The previous request had to be done using `pages` limitation.

#### Usage
```js
const ytsr = require('ytsr');

const firstResultBatch = await ytsr('github', { pages: 1 });
const secondResultBatch = ytsr.continueReq(firstResultBatch.continuation);
const thirdResultBatch = ytsr.continueReq(secondResultBatch.continuation);

// You can now use the .items property of all result batches e.g.:
console.log(firstResultBatch.items);
console.log(secondResultBatch.items);
console.log(thirdResultBatch.items);
```

* returns a Promise resolving into `{ continuation, items }`

# Related / Works well with

* [node-ytdl-core](https://github.com/fent/node-ytdl-core)
* [node-ytpl](https://github.com/TimeForANinja/node-ytpl)


# Install

    npm install --save ytsr

# License
MIT

---
_Source: https://npm.io/package/ytsr · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._