IMDb Movies Search & Detail Scraper

This actor discovers IMDb title pages from a keyword search, advanced title search, chart, or IMDb start URL, then opens every title page and emits an enriched record from IMDb's structured page state. It does not invent values, emit placeholder rows, or silently accept an IMDb verification page.

Reliable use

Use the default Apify Residential proxy configuration and a low maxConcurrency (2–3). IMDb can return a Human Verification shell (often HTTP 202/403/429); the actor detects this by response status, document title, and body markers, treats it as a failure, and writes no rows from that page.

maxItems is a hard cap, not a promise that IMDb has that many matching titles. The run fails on blocked/failed requests or zero usable records; a naturally shorter result set succeeds with a warning.

Inputs

Input	Meaning
mode	search, advancedSearch, startUrls, or topChart.
searchQuery	Required for keyword search.
startUrls	IMDb-only list/search/chart URLs; required for startUrls.
topChart	top250, top250tv, bottom100, moviemeter, or tvmeter.
maxItems	Maximum enriched titles requested (1–500).
maxConcurrency	Concurrent Chromium pages (1–5; default 2).
filters	titleType, genres, year/rating/vote ranges, languages, countries, certificates, and sortBy apply to advanced search.

Output contract

Every row has at least 25 populated fields. Optional IMDb values are omitted when IMDb does not publish them—there are no null, blank string, empty array, or empty-object values. The reserved top-level keys id, title, and description are intentionally not used; use titleId, titleName, and plot.

Common fields include IMDb identifiers and URLs, release/runtime/rating data, genres, credits, cast, countries and languages, images/trailers, review and award counts, and browser/proxy/source provenance. Values are derived from the current IMDb title page's JSON-LD or Next.js state.

Example input

{
  "mode": "search",
  "searchQuery": "Inception",
  "maxItems": 10,
  "maxConcurrency": 2,
  "genres": ["Drama"],
  "ratingMin": 7
}

Example output

{
  "recordType": "imdb-title",
  "titleId": "tt1375666",
  "titleName": "Inception",
  "titleType": "movie",
  "releaseYear": 2010,
  "genres": ["Action", "Sci-Fi", "Thriller"],
  "imdbRating": 8.8,
  "voteCount": 2500000,
  "plot": "A thief who steals corporate secrets through dream-sharing technology.",
  "primaryImageUrl": "https://m.media-amazon.com/images/example.jpg",
  "resultPosition": 1,
  "scrapingTimestamp": "2026-08-18T00:00:00.000Z"
}

Local checks

Run npm test for input/URL contract tests, npm run lint for syntax checks, and npm run validate-dataset after a local run. The dataset validator rejects partial records, empty nested values, schema type mismatches, and reserved keys.