TMDB + Rotten Tomatoes + Metacritic Scraper

One actor, three sources of movie/TV/people metadata. Switch the source via the platform dropdown.

• TMDB — themoviedb.org official REST API. Requires a free API key. Search, lookup-by-ID, browse popular / top rated / upcoming / now-playing / trending, discover with filters, person filmography, and the full append_to_response toolkit (credits, videos, similar, recommendations, keywords, external IDs, alternative titles, translations).
• Rotten Tomatoes — server-rendered HTML scraping (no auth). Search, browse popular, browse upcoming / in-theaters / at-home, look up movie or TV detail by slug or URL. Returns Tomatometer, Audience Score, certified-fresh status, cast, directors, synopsis.
• Metacritic — server-rendered HTML scraping (no auth). Search, browse top scores, browse by year / genre / sort, look up movie or TV detail by slug or URL. Returns Metascore, User Score, synopsis, content rating, genres, cast, directors.

All three platforms emit a unified record shape: platform, recordType, title, year, rating, url, mediaType are always present (when available); platform-specific fields (tomatometer, metascore, tmdbId, etc.) live alongside.

Quick Start

1. Pick a platform — rottentomatoes (no auth, default), metacritic (no auth), or tmdb (free API key required).
2. Pick a mode — popular is the easiest no-input run.
3. (TMDB only) paste a free API key from https://www.themoviedb.org/settings/api into tmdbApiKey.
4. Run. The default daily test (

   platform=rottentomatoes, mode=popular, maxItems=10
   ) returns ~10 records with no auth and no proxy.

Use cases

• Build a "best films of
• Cross-reference critic vs. audience scores for any title (TMDB vote, Tomatometer, Audience, Metascore, User Score).
• Pull a director's full TMDB filmography in a single run.
• Browse Metacritic's all-time top movies sorted by Metascore.
• Search any of the three platforms by free-text query and follow each result to its detail page for full metadata.

Inputs

The schema is fully self-documenting in the Apify console. Highlights:

Field	Required?	Description
platform	yes	tmdb, rottentomatoes, or metacritic.
mode	yes	search, byTitle, byUrl, byPerson, byGenre, byYear, popular, topRated, trending, upcoming, nowPlaying, discover.
tmdbApiKey	yes when platform=tmdb	Free API key from https://www.themoviedb.org/settings/api.
searchQuery	yes when mode=search	Free-text query.
titles	yes when mode=byTitle	TMDB IDs / RT slugs / MC slugs.
urls	yes when mode=byUrl	Full URLs. Auto-detects platform per URL.
mediaType	optional	movie, tv, person, multi (TMDB search only).
genre	optional	Dropdown — Action, Drama, Sci-Fi, etc. Maps to TMDB IDs; substring filter for RT/MC.
year / yearMin / yearMax	optional	Year filters.
minRating / maxRating	optional	Rating filters (TMDB 0-10, RT/MC 0-100).
containsKeyword	optional	Title substring filter.
language	optional	TMDB locale (en-US, fr-FR, ...). RT/MC English only.
region	optional	TMDB region code (US, GB, ...).
sortBy	optional	TMDB discover sort order.
tmdbList	optional	TMDB curated list when mode=popular/topRated/upcoming/nowPlaying.
trendingWindow	optional	TMDB trending window: day or week.
rtBrowseList	optional	RT browse listing (in theaters / at home / coming soon / TV series).
mcBrowseSort	optional	Metacritic browse sort.
appendToResponse	optional	TMDB append_to_response extras: credits, videos, images, reviews, similar, recommendations, keywords, release_dates, external_ids, alternative_titles, translations.
fetchDetail	optional, default true	Follow each list-item to the detail page for full metadata.
maxItems	optional, default 10	Hard cap on emitted records.
autoEscalateOnBlock	optional, default true	Auto-engage Apify Proxy on RT/MC HTTP 403/429 blocks.

Output

Every record carries:

• platform — tmdb, rottentomatoes, or metacritic.
• recordType — movie, tv, or person.
• mediaType — same as recordType for media entries.
• title — display name.
• year — first release year (when available).
• rating — primary rating on each platform (TMDB vote_average 0-10, RT Tomatometer 0-100, MC Metascore 0-100).
• url — canonical URL on the platform.
• scrapedAt — ISO-8601 timestamp.

Platform-specific fields populate when present:

• TMDB: tmdbId, voteCount, popularity, posterUrl, backdropUrl, genres (names), genreIds, cast, crew, videos, similar, recommendations, keywords, imdbId, tvdbId, runtime, tagline, status, homepage, budget, revenue, productionCompanies, spokenLanguages, numberOfSeasons, numberOfEpisodes, networks, createdBy, originalTitle, originalLanguage, overview, releaseDate, firstAirDate, lastAirDate, originCountry, inProduction, adult, biography, birthday, deathday, placeOfBirth, gender, alsoKnownAs, knownFor, knownForDepartment.
• Rotten Tomatoes: tomatometer, audienceScore, tomatometerCertified, tomatometerSentiment, audienceSentiment, criticsReviewCount, cast, directors, genres, synopsis, posterUrl, slug, endYear, datePublished.
• Metacritic: metascore, userScore, criticsReviewCount, cast, directors, genres, synopsis, contentRating, posterUrl, slug, releaseDate.

Modes per platform

Mode	TMDB	Rotten Tomatoes	Metacritic
search	text query (movie / tv / person / multi)	text query	text query
byTitle	TMDB ID lookup	RT slug → detail	MC slug → detail
byUrl	TMDB URL → detail	RT URL → detail	MC URL → detail
byPerson	full filmography	(TMDB only)	(TMDB only)
byGenre	discover with with_genres=ID	browse + substring filter	browse with genre=
byYear	discover with primary_release_year=Y	browse + filter	browse with releaseYearMin/Max=Y
popular	/movie/popular or /tv/popular	/browse/movies_at_home/sort:popular	/browse/movie/?sort=metascore_desc
topRated	/movie/top_rated or /tv/top_rated	/browse/.../sort:top_box_office	/browse/movie/?sort=metascore_desc
trending	/trending/{movie|tv|person}/{day|week}	/browse/.../sort:popular	/browse/.../sort=userscore_desc
upcoming	/movie/upcoming	/browse/movies_coming_soon	/browse/.../sort=releasedate_desc
nowPlaying	/movie/now_playing	/browse/movies_in_theaters/sort:popular	n/a
discover	/discover/movie or /discover/tv	(TMDB only)	(TMDB only)

How charging works

Charging is configured at the platform level (consumption pricing on Apify). The actor itself does not contain pricing logic — adjust on the Apify console.

Limitations

• TMDB requires a free API key at https://www.themoviedb.org/settings/api. Without it, the actor emits a status message and 0 records — by design (TMDB's terms forbid sharing the actor author's key).
• RT and MC are English-only — they don't expose localized titles. If you set language=fr-FR, TMDB returns French titles; RT/MC ignore the setting.
• RT pagination is single-page for popular / browse listings (~50 items per fetch). MC supports ?page=N (≤5 pages, ≈25 records each).
• Some RT pages don't expose Audience Score before opening night; the field is omitted (per the omit-empty rule).
• MC userScore is 0-10 (not 0-100 like Metascore). Both fields are emitted side-by-side when available.
• Record types are flat — cast is a list of strings on RT/MC but a list of {name, character, tmdbId} objects on TMDB. Filter / project accordingly downstream.
• Daily test default: platform=rottentomatoes, mode=popular, maxItems=10. This produces ≥1 record without any user-supplied secrets. For TMDB modes, set tmdbApiKey on the test page.
• Robots / search paths: rottentomatoes.com and metacritic.com robots.txt lists /search under Disallow: * (no Crawl-delay). The actor's mode=search only runs on explicit user-supplied queries (not bulk discovery) and paces requests at 0.25-0.3s. Detail / browse modes use unrestricted paths (/m/, /tv/, /movie/, /browse/). TMDB calls hit the official api.themoviedb.org REST endpoint under your own API key.

FAQ

Q: Can I cross-reference TMDB / RT / Metacritic scores in a single run? Run the actor 3 times (once per platform) with the same searchQuery, and join the datasets on title + year downstream.

Q: How do I get TMDB credits in the same record as the movie? Set mode=byTitle, platform=tmdb, appendToResponse=["credits"]. The actor calls /movie/{id}?append_to_response=credits and flattens the cast into the record.

Q: Why do some RT records lack synopsis? RT renders synopsis inside a <drawer-more> only on detail pages, not search/browse cards. With fetchDetail=true (default), the actor follows each card to the detail page; if the page layout differs (older titles), synopsis is omitted (per the omit-empty rule).

Q: Why is mode=byPerson TMDB-only? RT and Metacritic do expose celebrity pages, but they don't list the full filmography programmatically (links scatter across separate "More Movies" / "More TV" sections). TMDB's /person/{id}/movie_credits endpoint cleanly returns the full credits list.

Q: Why do some discover queries return 0 records? TMDB enforces a vote_count.gte floor; if you pair vote_average.desc with a low minVoteCount, you'll get obscure 10/10 titles. Bump minVoteCount to ~50 for "real" top titles.

Q: What happens on RT/MC anti-bot blocks? The actor auto-escalates to Apify Proxy (datacenter → residential) on HTTP 403/429. Set autoEscalateOnBlock=false to disable.