imdby 0.1.6

Scrape IMDb movies, people, companies, charts, and reviews in Python - no official API required.

🎬 imdby

Scrape the IMDb database from Python — movies, people, companies, events, characters, news, charts, and reviews — no official API key required.

If imdby saves you time, please consider giving it a ⭐ — it helps others discover the project.

---

📑 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)

Method	Returns (key attributes)
search_movie(text)	.title_name, .title_id
search_person(text)	.name, .person_id
search_company(text)	.company_name, .company_id
search_event(text)	.event_name, .event_id
search_character(text)	.character_name, .character_id
search_news(text)	.news_title, .news_id

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

Method	Data
movie(title_id)	Title, rating, votes, genres, metascore, budget/gross, storyline
plot(title_id)	Plot summary and synopsis
plot_keywords(title_id)	Plot keyword list
taglines(title_id)	Taglines list
full_cast_and_crew(title_id)	Directors, writers, cast, producers, music, cinematography, editing, casting
company(title_id)	Production companies, distributors, special effects, other companies
release_info(title_id)	Release dates by country, India release date, "Also Known As" titles
ratings(title_id)	Rating breakdown by demographic and region
parental_guide(title_id)	MPAA rating, certificates, and content advisories (nudity, violence, profanity, alcohol, frightening, spoilers)
technical_spec(title_id)	Runtime, sound mix, color, aspect ratio, camera, film format
critic_reviews(title_id)	Critic review scores and summaries
external_reviews(title_id)	Links to external critic reviews
external_sites(title_id)	Official sites, miscellaneous sites, photos, video links
user_reviews(title_id, remove_spoiler)	User reviews with per-review and aggregate sentiment scores (uses Selenium/Chrome)

Charts and listings (no arguments)

Method	Data
imdb_charts()	Top 250, Top 250 (English), Bottom 100, box office, MovieMeter, Top TV, TVMeter
top_india_charts()	Top rated Indian, Tamil, Telugu, and Malayalam movies
trending_now_in_india()	Upcoming, popular Tamil/Telugu/India/global/Hindi titles
upcoming_releases()	Interactive: pick a region, then lists upcoming releases there

---

🆘 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.