DOCSEARCHbyAlgolia
Submit Docs

torrent-api-py

repository·main·Indexed 19 days ago

https://github.com/ryuk-me/torrent-api-py

An unofficial Python-based API that aggregates search, trending, and recent data from multiple torrent indexing websites, including 1337x, PirateBay, Torrent Galaxy, and others. Built with FastAPI, it provides endpoints for site-specific and global searches, category filtering, and health monitoring. Supports authentication via API keys and can be deployed locally or via Docker Compose.

Tokens
2.7K
Snippets
12
Records
16
Agent score
65%

What's inside torrent-api-py

  1. Understand supported methods and site-specific capabilities

    main

    Each supported site has different capabilities regarding trending content, categories, and search limits. These configurations determine which API methods will work for a given site keyword.

    Key Configuration Fields:

    • trending_available: Boolean indicating if trending content can be fetched.
    • trending_category: Boolean indicating if trending content can be filtered by category.
    • search_by_category: Boolean indicating if searches can be scoped to a category.
    • recent_available: Boolean indicating if recent uploads can be fetched.
    • recent_category_available: Boolean indicating if recent uploads can be filtered by category.
    • categories: A list of supported category strings (e.g., "anime", "movies", "games").
    • limit: The default maximum number of results returned for that site.

    To change these defaults, modify helper/is_site_available.py.

    {
    "1337x": {
        "trending_available": true,
        "trending_category": true,
        "search_by_category": true,
        "recent_available": true,
        "recent_category_available": true,
        "categories": ["anime", "music", "games", "tv", "apps", "documentaries", "other", "xxx", "movies"],
        "limit": 100
    }
}

  2. Install and run Torrent-Api-py

    main

    Follow these steps to set up the environment, install dependencies, and start the API server locally.

    1. Clone and Navigate

    git clone https://github.com/Ryuk-me/Torrent-Api-py
cd Torrent-Api-py

    2. Set up Virtual Environment

    Install virtualenv, create a new environment named api-py, and activate it.

    Windows:

    pip install virtualenv
py -3 -m venv api-py
.\api-py\Scripts\activate

    Linux:

    pip install virtualenv
py -3 -m venv api-py
source api-py/bin/activate

    3. Install Dependencies and Start

    pip install -r requirements.txt
python main.py

    4. Access the API

    Once the server is running, access the API using a browser or API testing tool at: http://localhost:8009

    # Full sequence example
git clone https://github.com/Ryuk-me/Torrent-Api-py
cd Torrent-Api-py
pip install virtualenv
py -3 -m venv api-py
source api-py/bin/activate
pip install -r requirements.txt
python main.py

  6. Run the API using Docker Compose

    main

    You can deploy the torrent-api-py service using Docker Compose. The service is named api-py and maps the internal container port 8009 to host port 8009. After starting the container, the API will be accessible at http://localhost:8009.

    docker-compose up

  8. Search across all supported sites

    main

    Use the api/v1/all/search endpoint to perform a single query that searches across all configured torrent sites simultaneously.

    Parameters:

    • query (Required, string): The search term.
    • limit (Optional, integer): The number of results to fetch from each site. For example, if limit=5, you will receive 5 results per site.

    Example: api/v1/all/search?query=avengers&limit=5

    GET /api/v1/all/search?query=avengers&limit=5

  9. Get trending torrents

    main

    Retrieve trending torrents using either a site-specific or global endpoint.

    Site-specific trending: api/v1/trending

    • site (Required, string): The site identifier.
    • limit (Optional, integer): Number of results.
    • category (Optional, string): Filter by category.
    • page (Optional, integer): Page number.

    Global trending (all sites): api/v1/all/trending

    • limit (Optional, integer): Number of results.
    GET /api/v1/all/trending?limit=2

  10. Search for torrents on a specific site

    main

    Use the api/v1/search endpoint to search for torrents on a single specified site.

    Parameters:

    • site (Required, string): The identifier for the site (e.g., 1337x).
    • query (Required, string): The search term.
    • limit (Optional, integer): Number of results to return.
    • page (Optional, integer): The page number to retrieve (defaults to 1).
    GET /api/v1/search?site=1337x&query=avengers&limit=20

  11. Search for torrents by category on a specific site

    main

    Use the api/v1/category endpoint to search for torrents within a specific category on a single site.

    Parameters:

    • site (Required, string): The identifier for the site.
    • query (Required, string): The search term.
    • category (Required, string): The category to filter by (e.g., movies, tv).
    • limit (Optional, integer): Number of results to return.
    • page (Optional, integer): The page number to retrieve (defaults to 1).
    GET /api/v1/category?site=1337x&query=avengers&category=movies&limit=10

  12. Get recent torrents

    main

    Retrieve recently added torrents using either a site-specific or global endpoint.

    Site-specific recent: api/v1/recent

    • site (Required, string): The site identifier.
    • limit (Optional, integer): Number of results.
    • category (Optional, string): Filter by category.
    • page (Optional, integer): Page number.

    Global recent (all sites): api/v1/all/recent

    • limit (Optional, integer): Number of results.
    GET /api/v1/all/recent?limit=2