# Movie & TV Ratings Scraper (`mrdoe/movie-tv-ratings-scraper`) Actor Movie and TV ratings in one table: Rotten Tomatoes Tomatometer and Popcornmeter, Metacritic Metascore and user score, Letterboxd rating and IMDb link, with a combined score, cast, genres and poster. Search by title. No login. - **URL**: https://apify.com/mrdoe/movie-tv-ratings-scraper.md - **Developed by:** [MrDoe](https://apify.com/mrdoe) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.70 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ![Movie & TV Ratings Scraper - Movie and TV ratings from Rotten Tomatoes, Metacritic and Letterboxd with a combined score](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/movie-tv-ratings-scraper--hero.png) ### What does Movie & TV Ratings Scraper do? Movie & TV Ratings Scraper takes a list of movie or TV show titles and returns one row per title with the critic and audience scores from several rating sites side by side. Each row has the Rotten Tomatoes Tomatometer and Popcornmeter with review counts, the Metacritic Metascore and user score, the Letterboxd rating, a combined score on a 0 to 100 scale, the year, type, cast, director, genres, content rating, poster and links to the IMDb, Rotten Tomatoes, Metacritic and Letterboxd pages. Add a year to a title to pick the right version, or ask for several matches to include sequels and remakes. ### Why use Movie & TV Ratings Scraper? - See every major rating for a title in one row instead of opening four sites. - Rank a whole watchlist by one combined score. - Works for movies and TV shows, with an optional year to pick the right version. - Choose which rating sites to read, and how many matches to return per title. - Clean rows for watchlist spreadsheets, recommendation tools and media dashboards. ### What makes this different Scores from three rating sites are put on one scale and averaged into a single combined score, and every title is matched by name and year so the ratings belong to the same film. ### How it works ![Movie & TV Ratings Scraper workflow: your input, collection, output](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/movie-tv-ratings-scraper--how-it-works.png) 1. **Your input** β€” type one or more movie or TV show titles, with a year if you want a specific version. 2. **The Actor collects it** β€” the Actor finds each title and reads its ratings on the sites you selected. 3. **Your output** β€” you get one clean row per title with every score, the combined score and the page links. ### What data can you extract? The dataset has 30 fields per row: | Field | Type | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------------------ | | `id` | string | IMDb title ID. | | `inputTitle` | string | The search line this row came from. | | `title` | string | Official title. | | `year` | integer | Release year, or first air year for TV shows. | | `type` | string | movie or tv. | | `imdbUrl` | string | IMDb page. | | `posterUrl` | string | Poster image URL. | | `cast` | array | Main cast. | | `director` | string | Director. | | `genres` | array | Genres. | | `contentRating` | string | Content rating such as PG-13. | | `runtimeMinutes` | integer | Runtime in minutes; null when not available. | | `combinedScore` | number | Average of all available scores on a 0 to 100 scale. | | `sourcesCount` | integer | How many rating sites had this title. | | `rottenTomatoesUrl` | string | Rotten Tomatoes page. | | `tomatometerScore` | integer | Critics score in percent. | | `tomatometerReviews` | integer | Number of critic reviews. | | `tomatometerAverage10` | number | Average critic rating out of 10. | | `isCertifiedFresh` | boolean | True when the title is Certified Fresh. | | `popcornmeterScore` | integer | Audience score in percent. | | `popcornmeterRatings` | integer | Number of audience ratings. | | `metacriticUrl` | string | Metacritic page. | | `metascore` | integer | Metascore out of 100. | | `metacriticCriticReviews` | integer | Number of critic reviews. | | `metacriticUserScore10` | number | User score out of 10. | | `letterboxdUrl` | string | Letterboxd page. | | `letterboxdRating5` | number | Letterboxd rating out of 5. | | `letterboxdRatings` | integer | Number of Letterboxd ratings. | | `criticsConsensus` | string | Rotten Tomatoes critics consensus; only when review text is on. | | `reviews` | array | Review texts with source, type, author, score, date and text; only when review text is on. | ### How to use Movie & TV Ratings Scraper ![Movie & TV Ratings Scraper input form](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/movie-tv-ratings-scraper--input.png) 1. Open the Actor and go to the **Input** tab. 2. Enter one or more **Movie or TV show titles**, for example `Dune: Part Two`. 3. Optionally set filters and a **Max results** limit. 4. Click **Start**. A default run finishes in under a minute. 5. Open the **Output** tab, then download the dataset or connect it to your tools. ### Input Parameters | Parameter | Type | Required | Default | Description | | -------------------- | ------- | -------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `titles` | array | Yes | `["Dune: Part Two","Oppenheimer","Breaking Bad"]` | One title per line, for example "Dune: Part Two", "Oppenheimer" or "Breaking Bad". Add a year to pick the right version, for example "Dune 1984" or "Dune (2021)". Every title in this list is looked up; it is not limited by other settings. | | `mediaType` | string | No | `"any"` | Look for movies only, TV shows only, or both. | | `sources` | array | No | `["rottenTomatoes","metacritic","letterboxd"]` | Which sites to read ratings from. Leave all selected to get the combined score. | | `resultsPerTitle` | integer | No | `1` | How many matching titles to return for each search line. Use 1 for the best match, or up to 5 to also get sequels, remakes and same-name titles. | | `includeReviews` | boolean | No | `false` | Off by default. When on, each row also has the Rotten Tomatoes critics consensus and a few review texts from the selected sites (Metacritic critics and users, Letterboxd). For full review lists use the Movie & TV Reviews Scraper. | | `reviewsPerSource` | integer | No | `5` | How many reviews to include from each source for each title. Up to 50. | | `proxyConfiguration` | object | No | `{"useApifyProxy":false}` | Optional. Works without a proxy for normal use; turn on Apify Proxy for very large lists. | ### Output Data ![Movie & TV Ratings Scraper dataset table](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/movie-tv-ratings-scraper--output.png) `tomatometerScore` and `popcornmeterScore` are percentages. `metascore` is out of 100 and `metacriticUserScore10` is out of 10. `letterboxdRating5` is out of 5. `combinedScore` is the average of all available scores converted to a 0 to 100 scale. `sourcesCount` says how many sites had the title. Fields that do not apply are `null`. ![Movie & TV Ratings Scraper field map of one record](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/movie-tv-ratings-scraper--fields.png) A real dataset item: ```json { "id": "tt15239678", "inputTitle": "Dune: Part Two", "title": "Dune: Part Two", "year": 2024, "type": "movie", "imdbUrl": "https://www.imdb.com/title/tt15239678/", "posterUrl": "https://m.media-amazon.com/images/M/MV5BNTc0YmQxMjEtODI5MC00NjFiLTlkMWUtOGQ5NjFmYWUyZGJhXkEyXkFqcGc@._V1_.jpg", "cast": ["TimothΓ©e Chalamet", "Zendaya"], "director": "Denis Villeneuve", "genres": ["Sci-Fi", "Adventure", "Action", "Fantasy"], "contentRating": "PG-13", "runtimeMinutes": 167, "combinedScore": 87.3, "sourcesCount": 3, "rottenTomatoesUrl": "https://www.rottentomatoes.com/m/dune_part_two", "tomatometerScore": 92, "tomatometerReviews": 466, "tomatometerAverage10": 8.4, "isCertifiedFresh": true, "popcornmeterScore": 95, "popcornmeterRatings": 2244, "metacriticUrl": "https://www.metacritic.com/movie/dune-part-two/", "metascore": 79, "metacriticCriticReviews": 62, "metacriticUserScore10": 8.3, "letterboxdUrl": "https://letterboxd.com/film/dune-part-two/", "letterboxdRating5": 4.38, "letterboxdRatings": 3655095 } ``` ### Usage Examples #### Ratings for a watchlist ```json { "titles": ["Dune: Part Two", "Oppenheimer", "Poor Things"] } ``` #### Pick a specific version by year ```json { "titles": ["Dune 1984", "Dune (2021)"], "mediaType": "movie" } ``` #### TV shows only, Rotten Tomatoes and Metacritic ```json { "titles": ["Breaking Bad", "The Bear"], "mediaType": "tv", "sources": ["rottenTomatoes", "metacritic"] } ``` ### Tips for Best Results - Add the year, for example Dune (2021), when several films share a name. - Set Matches per title to 3 to include sequels and remakes of a series. - Deselect a rating site if you only need scores from the others. - Sort the output by combinedScore to rank a watchlist. ### Known Limitations - IMDb ratings are not included; the IMDb page link is provided. - Review text is off by default; turn on Include review text for a few reviews per source, or use the Movie & TV Reviews Scraper for full lists. - Letterboxd covers films only, so TV shows have no Letterboxd rating. - Very new or obscure titles may not be on every rating site, so some scores are null. - Scores change over time and reflect the moment of the run. ### Integrations Run it from the Apify API, on a schedule, or from a webhook. Send results straight to Google Sheets, Make, Zapier, Slack or your own database with Apify's built-in integrations. ### Export Formats Download the dataset as JSON, CSV, Excel, XML, HTML table or RSS from the **Output** tab or the API. ### Frequently Asked Questions #### How do I get Rotten Tomatoes and Metacritic scores together? Enter the titles and run the Actor. Each row has the Tomatometer, Popcornmeter, Metascore and user score side by side. #### What is the combined score? The average of every available score, each converted to a 0 to 100 scale, so a title with all sites reads as one number. #### Does it work for TV shows? Yes. Set Movies or TV shows to TV shows only, or leave it on both. Letterboxd has no TV shows, so those rows have no Letterboxd rating. #### How do I pick between remakes with the same name? Add the year to the title, for example Dune (2021), or raise Matches per title to see several versions. #### Does it include review text? Not by default. Turn on Include review text to add the critics consensus and a few reviews from each site. Use the Movie & TV Reviews Scraper when you need many reviews. #### Is there a limit on the number of titles? No. Every title in the list is looked up. #### How fresh is the data? Ratings are read live on every run. #### Do I need an account or login? No. The Actor collects public rating pages and needs no account, cookies or API key. #### Am I charged for failed runs or empty results? You are only charged for results that are actually written to the dataset. #### Can I run it on a schedule? Yes. Create a Task with your input and add a schedule in Apify Console. With monitor mode on, each scheduled run returns only what changed since the previous one. ### Support Questions or a missing field? Open an issue from the **Issues** tab on this Actor's page and it will be looked at. ### Legal / Responsible Use You are responsible for using the collected data in line with the terms of the rating sites and applicable law. The Actor collects only public rating information and no personal data. It is not affiliated with Rotten Tomatoes, Metacritic, Letterboxd or IMDb. # Actor input Schema ## `titles` (type: `array`): One title per line, for example "Dune: Part Two", "Oppenheimer" or "Breaking Bad". Add a year to pick the right version, for example "Dune 1984" or "Dune (2021)". Every title in this list is looked up; it is not limited by other settings. ## `mediaType` (type: `string`): Look for movies only, TV shows only, or both. ## `sources` (type: `array`): Which sites to read ratings from. Leave all selected to get the combined score. ## `resultsPerTitle` (type: `integer`): How many matching titles to return for each search line. Use 1 for the best match, or up to 5 to also get sequels, remakes and same-name titles. ## `includeReviews` (type: `boolean`): Off by default. When on, each row also has the Rotten Tomatoes critics consensus and a few review texts from the selected sites (Metacritic critics and users, Letterboxd). For full review lists use the Movie & TV Reviews Scraper. ## `reviewsPerSource` (type: `integer`): How many reviews to include from each source for each title. Up to 50. ## `proxyConfiguration` (type: `object`): Optional. Works without a proxy for normal use; turn on Apify Proxy for very large lists. ## Actor input object example ```json { "titles": [ "Dune: Part Two", "Oppenheimer", "Breaking Bad" ], "mediaType": "any", "sources": [ "rottenTomatoes", "metacritic", "letterboxd" ], "resultsPerTitle": 1, "includeReviews": false, "reviewsPerSource": 5, "proxyConfiguration": { "useApifyProxy": false } } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "titles": [ "Dune: Part Two", "Oppenheimer", "Breaking Bad" ], "sources": [ "rottenTomatoes", "metacritic", "letterboxd" ], "resultsPerTitle": 1 }; // Run the Actor and wait for it to finish const run = await client.actor("mrdoe/movie-tv-ratings-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "titles": [ "Dune: Part Two", "Oppenheimer", "Breaking Bad", ], "sources": [ "rottenTomatoes", "metacritic", "letterboxd", ], "resultsPerTitle": 1, } # Run the Actor and wait for it to finish run = client.actor("mrdoe/movie-tv-ratings-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "titles": [ "Dune: Part Two", "Oppenheimer", "Breaking Bad" ], "sources": [ "rottenTomatoes", "metacritic", "letterboxd" ], "resultsPerTitle": 1 }' | apify call mrdoe/movie-tv-ratings-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,mrdoe/movie-tv-ratings-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/Vq5RvOGafEbVWjRpP/builds/p0Vot5rocLE61m4uB/openapi.json