📑 Table of Contents

• Why imdby?
• Features
• Dependencies
• Installation
• Quick Start
• API Overview
• Getting Help
• Contributing
• Star History
• Contributors
• License

💡 Why imdby?

IMDb doesn't offer a public API, and existing solutions are often abandoned or limited to a narrow slice of the site. imdby scrapes IMDb's own pages directly and hands the result back as ready-to-use Python objects and pandas DataFrames — no scraping boilerplate, no API key, no rate-limit approval process.

🚀 Features

• Retrieve IMDb data for a title: overview, plot, plot keywords, taglines, full cast & crew, company credits, release info, ratings breakdown, parental guide, technical specs, critic reviews, and external reviews/sites.
• Retrieve IMDb charts: Top 250, Top 250 (English), Bottom 100, box office, MovieMeter/TVMeter, Top TV, and India-specific charts (Tamil, Telugu, Malayalam, trending, upcoming).
• Scrape a title's user reviews and score them with VADER and TextBlob sentiment analysis.
• Look up IMDb IDs for a title, person, company, event, character, or news item by search text.
• Results come back as plain Python objects and pandas DataFrames, ready for further analysis.
• Compatible with Python 3.10+ (tested through Python 3.14).

📦 Dependencies

• beautifulsoup4 + lxml — HTML parsing
• requests — HTTP requests
• selenium — used only by user_reviews() to load additional review pages. Requires a local Google Chrome install; the matching chromedriver is downloaded automatically by Selenium's built-in Selenium Manager, so no separate driver package is needed.
• pandas — tabular results
• nltk (VADER) + textblob — review sentiment analysis. The VADER lexicon is downloaded automatically on first use.
• unidecode — text normalization

📥 Installation

Install the latest release from PyPI:

pip install imdby

Or install from GitHub for the latest, unreleased changes:

pip install git+https://github.com/santhoshse7en/imdby

✨ Quick Start

from imdb.imdb import IMDb

ia = IMDb()

# Fetch full cast and crew of a movie by IMDb ID
cast = ia.full_cast_and_crew('tt4154796')

print('Directors:')
for director in cast.directors_name:
    print(director)

# Fetch core movie details
movie = ia.movie('tt4154796')
print(movie.title, movie.rating, movie.genre)

# Browse the IMDb Top 250 as a DataFrame
charts = ia.imdb_charts()
print(charts.top_rated_movies_df.head())

# Search for a person (prompts for a serial number from the printed matches)
people = ia.search_person('Simon Baker')
print(people.person_id, people.name)

Note: the search_* methods (search_movie, search_person, search_company, search_event, search_character, search_news) and upcoming_releases() are interactive — they print numbered suggestions to the console and use input() to read your selection.

📖 API Overview

All methods are called on an IMDb() instance.

Search (interactive, resolves a name to an IMDb ID)

Title details (take a title_id, e.g. 'tt4154796')

Charts and listings (no arguments)

🆘 Getting Help

• 📚 Official documentation
• 🐛 Report a bug or request a feature

🤝 Contributing

Contributions of all sizes are welcome — bug fixes, new IMDb pages, documentation, or tests.

1. Fork the repo and clone your fork.

2. Create a virtual environment and install in editable mode with dev tools:

   pip install -e ".[dev]"
   

3. Make your changes, then lint and verify the package still builds cleanly:

   ruff check imdb/
   python -m build
   python -m twine check dist/*
   

4. Open a pull request describing what changed and why.

If you're planning a significant change, please open an issue first to discuss your approach.

⭐ Star History

👥 Contributors

Big thanks to all the contributors who help make imdby better:

• M Santhosh Kumar – @santhoshse7en (author & maintainer)
• Sai Harsha Kurapati – @harshasic

Want to see your name here? Check out the Contributing section and send a pull request!

📄 License

This project is licensed under the MIT License.