🎬 Movie Recommender System

A content-based movie recommendation web app built with Streamlit, pandas, and scikit-learn, using The Movie Database (TMDB) API to fetch posters and metadata.

Users select a movie title and instantly receive similar movie recommendations displayed in a clean grid layout with posters.

---

🚀 Live Demo

👉 Deployed App:

https://movie-recommendator-eab5e0de6981.herokuapp.com

📸 Screenshots

Home Page

![Home Page](screenshots/Screenshot 2026-01-31 at 22.30.23.png)

Recommendations View

![Recommendations](screenshots/Screenshot 2026-01-31 at 22.34.29.png)
![Recommendations](screenshots/Screenshot 2026-01-31 at 22.32.25.png)
![Recommendations](screenshots/Screenshot 2026-01-31 at 22.32.58.png)

Deployed App

![Deployed App](screenshots/Screenshot 2026-01-31 at 22.30.04.png)

🏗️ Architecture Diagram

High-level flow of the system:

User
  ↓
Streamlit UI
  ↓
Content-Based Model (Cosine Similarity)
  ↓
Pickle Files (movies.pkl + similarity.pkl)
  ↓
TMDB API → Poster Images

🚀 Features

• Content-based recommendation using cosine similarity
• Interactive Streamlit UI
• Poster images fetched from TMDB API
• Responsive grid layout
• Ready for cloud deployment (Heroku-style Procfile included)

---

Movie Datasets link

https://www.kaggle.com/datasets/tmdb/tmdb-movie-metadata?resource=download

📁 Project Structure

.
├── app.py                          # Streamlit application
├── movies.pkl                      # Movie metadata
├── similarity.pkl                  # Precomputed similarity matrix
├── movies_recommender_system.ipynb # Model training / preprocessing notebook
├── Procfile                        # Deployment entrypoint
├── requirements.txt               # Python dependencies
├── screenshots/ # App images
└── README.md

---

🧠 How It Works

1. Movie metadata is loaded from movies.pkl.
2. A cosine-similarity matrix (similarity.pkl) stores how close movies are to each other.
3. When a user selects a movie:
   • The app finds the most similar titles.
   • TMDB’s API is called to fetch poster images.
4. Results are displayed in rows of five movies with titles and posters.

---

🔑 TMDB API Setup

This project requires an API key from The Movie Database.

Steps

1. Create an account at:
   https://www.themoviedb.org
2. Generate an API key.
3. Set it as an environment variable.

---

Local

export TMDB_TOKEN="your_api_key_here"

Heroku

heroku config:set TMDB_TOKEN="your_api_key_here"

In app.py

TMDB_TOKEN = os.getenv("TMDB_TOKEN")

⚠️ Never hard-code secrets in production.

🖥️ Running Locally

Create a virtual environment and install dependencies:

pip install -r requirements.txt

Run the app:

streamlit run app.py

Open in your browser:

http://localhost:8501

☁️ Deployment (Heroku)

Your Procfile should contain:

web: streamlit run app.py --server.port=$PORT --server.address=0.0.0.0

Deploy:

git push heroku main

Check logs if anything fails:

heroku logs --tail

🧪 Common Issues

• Posters Not Showing
• Check TMDB key is valid
• Ensure HTTPS is used for images
• Confirm poster_path exists in the API response
• Restart Streamlit cache

App Crashes on Startup

• similarity.pkl may be too large for free dynos
• Missing dependencies in requirements.txt
• Wrong port binding in Procfile
• Streamlit config typos (server, not sever)

📊 Future Improvements

• Add movie overviews and ratings
• Cache poster URLs
• Show release year & genres
• Hybrid recommender with collaborative filtering
• Search instead of dropdown
• Database backend

✨ Tech Stack

• Python
• Streamlit
• pandas / NumPy
• scikit-learn
• Requests
• TMDB API
• Heroku

👩‍💻 Author

Shraddha Shelar

AI / Data Science Enthusiast Movie Recommendation Systems | NLP | ML Engineering