# torrent-search-api

> Yet another node torrent scraper based on x-ray. (Support iptorrents, torrentleech, torrent9, Yyggtorrent, ThePiratebay, torrentz2, 1337x, KickassTorrent, Rarbg, TorrentProject, Yts, Limetorrents, Eztv)

Latest version **2.1.4** (published 2021-05-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install torrent-search-api
pnpm add torrent-search-api
yarn add torrent-search-api
bun add torrent-search-api
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.4 |
| Published | 2021-05-29 |
| First published | 2017-01-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/torrent-search-api) |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 507.7 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 459 |
| Author | Jimmy Laurent |
| Maintainers | jimmylaurent |
| Keywords | torrent, scraper, crawler, node, api, yggtorrent, torrentz2, torrentleech, iptorrents, 1337x, thepiratebay, tpb, kickasstorrents, rarbg, torrentproject, yts, eztv, limetorrents |

## Links

- npm: https://www.npmjs.com/package/torrent-search-api
- Repository: https://github.com/JimmyLaurent/torrent-search-api
- Homepage: https://github.com/JimmyLaurent/torrent-search-api#readme
- Issues: https://github.com/JimmyLaurent/torrent-search-api/issues
- npm.io page: https://npm.io/package/torrent-search-api

## Dependencies (5)

- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [request](https://npm.io/package/request.md) ^2.88.2
- [cloudscraper](https://npm.io/package/cloudscraper.md) ^4.6.0
- [string-format](https://npm.io/package/string-format.md) ^0.5.0
- [x-ray-scraper](https://npm.io/package/x-ray-scraper.md) ^3.0.5

## 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

- 2.1.4 (latest) — 2021-05-29
- 2.1.3 — 2020-06-06
- 2.1.2 — 2020-06-06
- 2.1.1 — 2020-03-12
- 2.1.0 — 2020-03-11
- 2.0.10 — 2019-10-03
- 2.0.9 — 2019-05-25
- 2.0.8 — 2019-04-28
- 2.0.7 — 2019-04-05
- 2.0.6 — 2019-03-20
- 2.0.5 — 2019-01-27
- 2.0.4 — 2018-12-05
- 2.0.3 — 2018-08-29
- 2.0.2 — 2018-08-29
- 2.0.1 — 2018-08-29
- … 37 more at https://npm.io/package/torrent-search-api/versions

## README

# TorrentSearchApi

[![npm](https://img.shields.io/npm/dm/torrent-search-api.svg?maxAge=2592000)](https://npm-stat.com/charts.html?package=torrent-search-api)

Yet another node torrent search api based on x-ray.

## Install

```bash
npm install torrent-search-api
```

## Supported providers

- TorrentLeech: cookie authentification
- IpTorrents: credentials and cookie authentification
- Torrent9
- Torrentz2
- 1337x
- ThePirateBay
- YggTorrent : credentials and cookie authentification
- KickassTorrents
- Rarbg
- TorrentProject
- Yts
- Limetorrents
- Eztv

## Features

- **Search:** search torrents on multiples providers.

- **Torrent details:** get details about torrents (raw scraped html).

- **Download:** download torrents files.

- **Easily extensible:** you can easily add new providers and enjoy built-in features like cloudfare bypass.
 

## Quick Example

```js
const TorrentSearchApi = require('torrent-search-api');

TorrentSearchApi.enableProvider('Torrent9');

// Search '1080' in 'Movies' category and limit to 20 results
const torrents = await TorrentSearchApi.search('1080', 'Movies', 20);
```

# Torrent Search API

### Get providers

```js
// Get providers
const providers = TorrentSearchApi.getProviders();

// Get active providers
const activeProviders = TorrentSearchApi.getActiveProviders();

// providers
{
    {
        name: 'Torrent9',
        public: true,
        categories: ['All', 'Movies', 'TV', 'Music', 'Apps', 'Books', 'Top100']
    },
    {
        name: 'IpTorrents',
        public: false,
        categories: ['All', 'Movies', 'TV', 'Games', 'Music']
    },
    ...
}

```

### Enable provider

```js

// Enable public providers
TorrentSearchApi.enablePublicProviders();

// Enable public provider
TorrentSearchApi.enableProvider('Torrent9');

// Enable private provider with cookies
TorrentSearchApi.enableProvider('IpTorrents', ['uid=XXX;', 'pass=XXX;']);

// Enable private provider with credentials
TorrentSearchApi.enableProvider('IpTorrents', 'USERNAME', 'PASSWORD');

// Enable private provider with token
TorrentSearchApi.enableProvider('xxx', 'TOKEN');

```

### Disable provider

```js

// Disable provider
TorrentSearchApi.disableProvider('TorrentLeech');

// Disable all enabled providers
TorrentSearchApi.disableAllProviders();

```

### Check if a provider exists and is active

```js

TorrentSearchApi.isProviderActive('1337x');

```

### Search torrent

The result is an array of torrents sorted by seeders with more or less properties depending on the provider.

```js

// Search on actives providers
// Query: 1080
// Category: Movies (optional)
// Limit: 20 (optional)
const torrents = await TorrentSearchApi.search('1080', 'Movies', 20);

// Search with given providers
// query: 1080
// category: Movies (optional)
// limit: 20 (optional)
const torrents = await TorrentSearchApi.search(['IpTorrents', 'Torrent9'], '1080', 'Movies', 20);

```

### Torrent details

```js

// Get details (raw scraped html)
// torrent: taken from a search result
const torrentHtmlDetail = await TorrentSearchApi.getTorrentDetails(torrent);

```

### Torrent magnet

```js

// Get magnet url
// torrent: taken from a search result
const magnet = await TorrentSearchApi.getMagnet(torrent);

```

### Download torrent

```js

// Download a buffer
// torrent: taken from a search result
const buffer = await TorrentSearchApi.downloadTorrent(torrent);

// Download torrent and write it to the disk
// torrent: taken from a search result
await TorrentSearchApi.downloadTorrent(torrent, filnamePath);
```

### Load custom providers

You can code and add your custom providers (see provider definition format in existing providers)
Don't forget to enable your provider if you intend to use it.

```js

// load multipe providers
// from a TorrentProvider custom class definition or instance
const MyCustomProvider = require('./MyCustomProvider');
TorrentSearchApi.loadProvider(MyCustomProvider);

// from a provider object definition
TorrentSearchApi.loadProvider( {/* provider object definition */});

// from an absolute path to class definition or json object definition
const path = require('path');
const providerFullPath = path.join(__dirname, './lib/providers/MyCustomProvider');
TorrentSearchApi.loadProviders(providerFullPath);

// load multipe providers within a directory
// only absolute path are allowed
// it loads every *.json and *.js file
const path = require('path');
const providerDirFullPath = path.join(__dirname, './lib/providers/');
TorrentSearchApi.loadProviders(providerDirFullPath);

// load multipe providers
const MyCustomProvider = require('./MyCustomProvider');
TorrentSearchApi.loadProviders(MyCustomProvider, {/* provider object definition */}, ...);

```

### Remove provider

```js

// Remove provider
TorrentSearchApi.removeProvider('MyCustomProvider');

```

### Create TorrentSearchApi instance

If you want to create an instance of the api without loading all the default providers and only load the ones that you want

```js

// create instance
const createApi = require('torrent-search-api/createApi');
const TorrentSearchApi = createApi(/* same arguments as "loadProviders" method */)

```

### Create a new provider

Check "test/createProvider.test.js" file if you want to create a new provider.

Running tests command

```bash
npm run test:watch
```

### Override provider config
 ```js
 // Fully or partial override of the provider config
TorrentSearchApi.overrideConfig(providerName, newConfig);
 ```

## License

MIT © 2020 [Jimmy Laurent](https://github.com/JimmyLaurent)

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