Turrie — Movie Discovery Bot

Turrie is a Telegram bot built with Python and FastAPI that helps users discover movies, watch trailers, and check streaming availability across different regions. It leverages the TMDB (The Movie Database) API to provide accurate and up-to-date movie information.

Features

• Movie Search: Search for any movie by title.
• Detailed Info: Get ratings, release years, and overview summaries.
• Streaming Availability: Find out where to Stream, Rent, or Buy movies (Netflix, Prime Video, Apple TV, etc.).
• Region Support: Switch regions to get accurate provider data for:
  • 🇮🇳 India
  • 🇺🇸 USA
  • 🇬🇧 UK
  • 🇨🇦 Canada
  • 🇦🇺 Australia
• Trailers: Direct links to watch official trailers on YouTube.
• Pagination: Browse through search results easily with "Next" and "Previous" navigation.

Tech Stack

• Language: Python 3.10.13
• Framework: FastAPI (for Webhook handling)
• Bot Library: python-telegram-bot
• Server: Uvicorn
• API: The Movie Database (TMDB)
• Deployment: Render

Project Structure

turrie/
├── app/
│   ├── bot.py          # Bot application builder and command registration
│   ├── handlers.py     # Logic for text, commands, and callback queries
│   ├── main.py         # FastAPI entry point & Webhook lifecycle management
│   └── movies.py       # TMDB API integration functions
├── .env                # Environment variables (not committed)
├── .gitignore          # Git ignore rules
├── render.yaml         # Render deployment configuration
├── requirements.txt    # Python dependencies
└── runtime.txt         # Python runtime version

Getting Started

Prerequisites

• Python 3.10 or higher
• A Telegram Bot Token (from @BotFather)
• A TMDB API Key (from TMDB)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/turrie.git
cd turrie

2. Install dependencies

pip install -r requirements.txt

3. Create a .env file in the root directory and add the following keys:

BOT_TOKEN=your_telegram_bot_token
TMDB_API_KEY=your_tmdb_api_key
WEBHOOK_URL=https://your-app-url.onrender.com/webhook
# Optional defaults:
BASE_URL=https://api.themoviedb.org/3
IMAGE_URL=https://image.tmdb.org/t/p/w500

Run locally

Since the bot is configured to use Webhooks via FastAPI, running it locally requires a public HTTPS URL (using tools like ngrok).

1. Start the server:

uvicorn app.main:app --reload

2. Expose your local server (e.g., using ngrok)

ngrok http 8000

3. Update .env to set WEBHOOK_URL to your ngrok URL, i.e., https://xxxx.ngrok.io/webhook.

Render Deployment

This project includes a render.yaml file for easy deployment on Render.

1. Push your code to GitHub.
2. Connect your repository to Render.
3. Render will automatically detect the render.yaml configuration.

Important: Add your environment variables (BOT_TOKEN, TMDB_API_KEY, WEBHOOK_URL) in the Render dashboard settings.

Bot Commands

• /start - Initialize the bot and see the welcome message.
• /region - Select your preferred country for streaming availability.
• /help - View help instructions.
• Text Search - Simply type a movie name to search. (e.g., "Interstellar")

License

This project is open-source.

Acknowledgements

Data provided by The Movie Database (TMDB). (Thank you so much for your free api services 🙏)

This product uses the TMDB API but is not endorsed or certified by TMDB.