imdb-scraper

Scrape IMDb search results as clean, structured JSON or CSV — title, IMDb id, original title, release year, runtime, certificate, genre, plot, IMDb rating, vote count, Metascore, poster image and title URL — for any title type, genre, year range and sort order. Ships a CLI and a small Python library.

Powered by ScrapeUnblocker. IMDb is rendered behind heavy anti-bot protection, so this project fetches pages through the ScrapeUnblocker getPageSource parsed-data API: it returns AI-parsed JSON instead of raw HTML, so there are no brittle CSS selectors to maintain.

Features

• 🎬 Query IMDb's advanced search by title text, title type, genre, release year range, minimum vote count and sort order.
• 🧾 Typed Title records with clean fields: imdb_rating and metascore as numbers, vote_count and release_year as ints, runtime_minutes derived from IMDb's runtime, and a ready-to-open canonical title url.
• ↕️ Sort presets: votes, rating, popularity, newest, oldest, alphabetical, runtime, boxoffice — plus a raw --sort-token passthrough.
• 🌍 Country targeting (defaults to US) — IMDb localises titles by geo, so this keeps titles in English out of the box; original_title is always available.
• 🧺 Multi-genre collection with automatic de-duplication by IMDb id.
• 📤 Output as JSON, CSV, or a readable table.
• 🔁 Automatic retry on transient upstream errors.
• ✅ Offline unit tests that mock the SDK — no API credit spent in CI.

Install

pip install .
# or, for development (tests + linter):
pip install -e ".[dev]"

Set your API key (get one at scrapeunblocker.com):

export SCRAPEUNBLOCKER_KEY=your_key_here   # see .env.example

CLI usage

# Most-rated feature films, as a table
imdb-search --sort votes --count 10 --format table

# Top-rated sci-fi of the 2010s with a vote floor, exported to CSV
imdb-search --genre sci-fi --sort rating --year-from 2010 --year-to 2019 \
            --min-votes 50000 --format csv -o scifi.csv

# Search a title across TV series, newest first
imdb-search "batman" --type tv_series --sort newest

# Collect across several genres, merged and de-duplicated by IMDb id
imdb-search --genre action --genre adventure --genre sci-fi --sort rating --count 50

usage: imdb-search [-h] [--type {feature,tv_movie,tv_series,...}] [--genre GENRE]
                   [--sort {alphabetical,boxoffice,newest,oldest,popularity,rating,runtime,votes}]
                   [--sort-token TOKEN] [--year YEAR] [--year-from YEAR_FROM]
                   [--year-to YEAR_TO] [--min-votes MIN_VOTES] [--count COUNT]
                   [--country XX] [--format {json,csv,table}] [--output FILE]
                   [--max-retries MAX_RETRIES] [--version]
                   [title]

Library usage

from imdb_scraper import ImdbScraper

scraper = ImdbScraper()  # defaults to US so titles come back in English

# Top-rated sci-fi with at least 50k votes
titles = scraper.search(genres="sci-fi", sort="rating", min_votes=50000, count=25)
for t in titles:
    print(t.imdb_rating, t.release_year, t.title, t.url)

# Collect across several genres, merged and de-duplicated by IMDb id
titles = scraper.search_genres(["action", "adventure"], sort="rating", count=50)

Or the one-shot helper:

from imdb_scraper import search

titles = search(title="inception", count=5)

Example output

[
  {
    "title_id": "tt0111161",
    "title": "The Shawshank Redemption",
    "original_title": "The Shawshank Redemption",
    "url": "https://www.imdb.com/title/tt0111161/",
    "release_year": 1994,
    "runtime_minutes": 142,
    "certificate": "R",
    "genre": "Drama",
    "imdb_rating": 9.3,
    "vote_count": 3237567,
    "metascore": 82,
    "production_status": null,
    "plot": "After a banker is sentenced to life in Shawshank Prison...",
    "image_url": "https://m.media-amazon.com/images/M/...jpg",
    "genre_query": null
  }
]

How it works & limits

• Each search maps to an IMDb search/title/ advanced-search page, fetched through ScrapeUnblocker's parsed-data API.
• One request returns up to 250 results (--count, IMDb's page cap) and exposes no next-page cursor. To build a larger, unique dataset, query several genres (or year ranges) and let search_genres merge and de-duplicate them.
• IMDb localises titles by geo. Requests default to --country US so titles come back in English; the original_title field is always populated as a fallback. genre reflects IMDb's primary genre for the title.
• Unreleased or minimal entries expose few fields; anything IMDb omits (rating, runtime, Metascore, …) comes back as null.

Project layout

src/imdb_scraper/
  __init__.py      # package exports + __version__
  models.py        # Title dataclass + field parsing helpers
  scraper.py       # ImdbScraper: URL building, retry, shaping
  cli.py           # argparse CLI (imdb-search)
examples/          # runnable quickstart / CSV export / multi-genre scripts
tests/             # offline unit tests (SDK mocked)

Development

make install   # editable install with dev deps
make lint      # ruff check
make format    # ruff format
make test      # pytest (offline, no API key needed)

Links

• Website: https://scrapeunblocker.com/?utm_source=github&utm_medium=integration&utm_campaign=example-repos
• Docs: https://docs.scrapeunblocker.com/?utm_source=github&utm_medium=integration&utm_campaign=example-repos

License

MIT © 2026 ScrapeUnblocker