# IMDb Scraper - Top 250 Movies & TV Shows Chart, Ratings (`clover_folktale/imdb-scraper`) Actor

Get the IMDb Top 250 movies chart or the Top 250 TV shows chart in one run: rank, title, original title, year, release date, IMDb rating, vote count, weighted rating and poster, in 10 languages. No login or cookies needed. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/clover_folktale/imdb-scraper.md
- **Developed by:** [Silkline](https://apify.com/clover_folktale) (community)
- **Categories:** Social media, Other
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

IMDb Scraper returns the IMDb Top 250 movies chart or the Top 250 TV shows chart, and the latest IMDb news by category, as clean, flat JSON, in one run. Every record has the chart rank, IMDb ID and link, title in your language and the original title, year, release date, IMDb rating, number of votes, the weighted rating IMDb ranks the chart by, and the poster. Pick one of 10 languages for the titles. It is for film and TV researchers, recommendation and list sites, newsletter writers and data teams who want an IMDb API alternative with no IMDb account, API keys, proxies or cookies. Pricing is pay-per-event: $0.0045 per record (a chart title or a news item), plus a $0.009 start fee per run.

### What data can you get?

Three modes, one record per item. Mode `chart`: one record per chart entry, in chart order.

| Field | What it contains |
|---|---|
| `rank` | Position in the chart (1 to 250) |
| `imdbId` | IMDb title ID (tt followed by digits) |
| `url` | Link to the IMDb title page |
| `title` | Title in the requested language |
| `originalTitle` | Title in its original language |
| `titleType` | IMDb title type, for example `movie`, `tvSeries` or `tvMiniSeries` |
| `year` | Release year (first year for a TV show) |
| `endYear` | Last year of a TV show; empty for movies and for shows that are not over |
| `releaseDate` | Release date IMDb lists first, as `YYYY-MM-DD` |
| `releaseDateCountry` | Country code of that release date |
| `rating` | IMDb user rating out of 10, as shown on the title page |
| `voteCount` | Number of votes behind the chart rating |
| `weightedRating` | The weighted rating IMDb ranks the chart by (more exact than `rating`) |
| `imageUrl` | Poster image |
| `chart` | Chart the title was read from: `movie` or `tv` |
| `language` | Language and country code the titles were requested in |
| `type` | Record type, always `chartEntry` |

#### Mode `news`: IMDb news by category

One record per news item, newest first (about 100 per run).

| Field | What it contains |
|---|---|
| `newsId` | IMDb news ID (`ni` followed by digits) |
| `imdbUrl` | Link to the news item on IMDb |
| `url` | Link to the original article on the publisher's site |
| `title` | Headline |
| `text` | News text as IMDb gives it: a plain-text excerpt that may stop mid-sentence |
| `publishedAt` | Publication time in UTC (ISO 8601) |
| `author` | Author named on the item (empty when none) |
| `sourceName`, `sourceUrl` | Publication the item comes from, and its section page |
| `imageUrl`, `imageWidth`, `imageHeight` | News image and its size |
| `category` | News section: `TOP`, `MOVIE`, `TV` or `CELEBRITY` |
| `language` | Language and country code requested |
| `type` | Always `newsItem` |

#### How the data is shaped

- **Numbers you can use.** `rank`, `year`, `voteCount`, `rating` and `weightedRating` are numbers.
- **Flat fields, nothing nested.** One record per title.
- **Not included.** No genres, cast, plot or reviews.

### How to use IMDb Scraper

1. Open the Actor in Apify Console.
2. Choose the mode: **Top 250 chart** or **News by category**.
3. For the chart, choose the **Chart**: Top 250 movies or Top 250 TV shows. For news, choose the **News category**.
4. Choose the **Language** of the titles and news.
5. Set **Max results**: the first N records (250 at most for a chart, about 100 news items).
6. Click **Start**. When the run finishes, download the dataset as JSON, CSV or Excel, or read it through the Apify API.

The Actor also runs in seconds with an empty input: `{}` returns the first 20 titles of the Top 250 movies.

### Input

| Field | Type | Required | What it does | Default |
|---|---|---|---|---|
| `mode` | string | Optional | `chart` (Top 250 chart), or `news` (news by category) | `chart` |
| `chart` | string | Optional | `movie` (Top 250 movies) or `tv` (Top 250 TV shows) | `movie` |
| `newsCategory` | string | Optional | Mode `news`: `TOP`, `MOVIE`, `TV` or `CELEBRITY` | `TOP` |
| `language` | string | Optional | Language of the titles and news: `en_US`, `fr_CA`, `fr_FR`, `de_DE`, `hi_IN`, `it_IT`, `pt_BR`, `es_ES`, `es_US`, `es_MX` | `en_US` |
| `maxResults` | integer | Optional | Number of records to return: titles from rank 1 downwards (a chart holds 250), news items newest first (about 100 per run). You are charged per record returned | `20` |

#### Example: the full Top 250 TV chart in German

```json
{
  "mode": "chart",
  "chart": "tv",
  "language": "de_DE",
  "maxResults": 250
}
```

#### Example: latest movie news

```json
{
  "mode": "news",
  "newsCategory": "MOVIE",
  "maxResults": 100
}
```

### Output example

Mode `chart`:

```json
{
  "type": "chartEntry",
  "rank": 1,
  "imdbId": "tt0111161",
  "url": "https://www.imdb.com/title/tt0111161/",
  "chart": "movie",
  "language": "en_US",
  "title": "The Shawshank Redemption",
  "originalTitle": "The Shawshank Redemption",
  "titleType": "movie",
  "year": 1994,
  "endYear": null,
  "releaseDate": "1994-10-14",
  "releaseDateCountry": "US",
  "rating": 9.3,
  "voteCount": 3258126,
  "weightedRating": 9.2408,
  "imageUrl": "https://m.media-amazon.com/images/M/example.jpg"
}
```

Mode `news`:

```json
{
  "type": "newsItem",
  "newsId": "ni66078173",
  "imdbUrl": "https://www.imdb.com/news/ni66078173/",
  "url": "https://www.hollywoodreporter.com/movies/movie-news/example/",
  "category": "MOVIE",
  "language": "en_US",
  "title": "Example headline",
  "text": "Example excerpt of the article...",
  "publishedAt": "2026-10-25T16:06:11Z",
  "author": "Example Author",
  "sourceName": "The Hollywood Reporter - Movie News",
  "sourceUrl": "http://www.hollywoodreporter.com/topic/movies",
  "imageUrl": "https://m.media-amazon.com/images/M/example.jpg",
  "imageWidth": 200,
  "imageHeight": 200
}
```

### How much does it cost?

The Actor uses pay-per-event pricing. These are the charge events and their prices:

| Event | Price (USD) | When it is charged |
|---|---|---|
| `run-start` | $0.009 | Once per run, charged when the request to the data source succeeds. It is not charged when the data source fails, or when your spending limit cannot cover it. |
| `result` | $0.0045 | For each record returned: a chart title or a news item |

Worked examples:

- **The default run (20 titles):** $0.009 + 20 x $0.0045 = **$0.099**.
- **A full chart (250 titles):** $0.009 + 250 x $0.0045 = **$1.134**.
- **Both full charts (two runs):** 2 x $1.134 = **$2.268**.
- **A full news run (about 100 items):** $0.009 + 100 x $0.0045 = **$0.459**.

You never pay for more than `maxResults` items, you are never charged for items that were not delivered, and the run stops by itself if your spending limit is reached.

On the free Apify plan, every run returns a sample dataset: a real result of this Actor's prefilled input, captured on the date shown in the run status, so you can see exactly what the output looks like. Your own input is not used and nothing is charged. To run your own queries, use any paid Apify plan.

### Use cases

- **Lists and newsletters:** publish the current Top 250 with ratings and vote counts.
- **Chart monitoring:** run daily or weekly and compare ranks and ratings over time.
- **Recommendation and catalog projects:** seed a catalog with IMDb IDs, years and posters.
- **News monitoring:** pull movie, TV or celebrity news on a schedule and feed a newsletter or alert.
- **Localised lists:** get the chart with titles in French, German, Spanish, Italian, Portuguese or Hindi.

### Integrations and API

You can start runs from your own code with the Apify API, schedule runs (for example a weekly chart snapshot), and connect the dataset to Apify integrations and webhooks. Results can be read from the API as JSON, CSV or Excel.

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("clover_folktale/imdb-scraper").call(run_input={
    "mode": "chart",
    "chart": "movie",
    "language": "en_US",
    "maxResults": 250,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["rank"], item["title"], item["rating"])
```

### Tips and limits

- **One request per run.** The whole chart or the latest news comes back at once, so a run takes a few seconds whatever `maxResults` is. You are charged only for the records you ask for. News is what IMDb shows now; there is no way to go back further.
- **Rating vs weighted rating.** `rating` is the number shown on the title page (one decimal). `weightedRating` is the more exact figure IMDb sorts the chart by.
- **Release date.** `releaseDate` is the first release date IMDb lists and can differ from `year` (for example a later re-release).
- **Titles in other languages.** `title` is the local release name where IMDb has one, otherwise the original title; `originalTitle` is always the original.
- **Free plan.** Every run on the free Apify plan returns a stored sample dataset; your own input is not used and nothing is charged.
- **Feedback.** Missing a field? Open an issue from the Actor page and it will be looked at.

### FAQ

#### Do I need an IMDb account, API key or cookies?

No. You only need an Apify account to run the Actor.

#### Is it legal to scrape IMDb?

The Actor returns only public data: what anyone sees on IMDb's Top 250 pages, and news pages. It returns no account data and no private data. You are responsible for how you use the data and for following the laws and terms that apply to you.

#### How fresh is the data?

Each run reads the chart or news at the time of the run.

#### Can I get one title's details, cast or reviews?

Not with this Actor. It returns the Top 250 charts and news.

#### Can I schedule runs and export the data?

Yes. You can schedule runs in Apify, start them through the API, and export every dataset as JSON, CSV or Excel.

### More tools from the same developer

- [Douban 豆瓣 Scraper - Movies, Ratings, Comments & Reviews](https://apify.com/clover_folktale/douban-scraper)
- [Amazon Product Scraper - Best Sellers, ASIN, Prices, Ratings](https://apify.com/clover_folktale/amazon-scraper)
- [Reddit Scraper - Posts, Comments & User IDs, No Login](https://apify.com/clover_folktale/reddit-scraper)

# Actor input Schema

## `mode` (type: `string`):

What to scrape: the IMDb Top 250 chart or the latest IMDb news in a category.

## `chart` (type: `string`):

Which chart to read: the Top 250 movies or the Top 250 TV shows.

## `newsCategory` (type: `string`):

Which IMDb news section to read: top news, movie news, TV news or celebrity news. One run returns the latest items of that section (about 100).

## `language` (type: `string`):

Language and country of the titles and news (a title is shown in its local release name where IMDb has one).

## `maxResults` (type: `integer`):

Maximum number of records to return: titles taken from rank 1 downwards (a chart holds 250), or news items newest first (about 100 per run). You are charged per record returned.

## Actor input object example

```json
{
  "mode": "chart",
  "chart": "movie",
  "newsCategory": "TOP",
  "language": "en_US",
  "maxResults": 20
}
```

# Actor output Schema

## `results` (type: `string`):

All scraped items (JSON, CSV, Excel via the dataset API).

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_folktale/imdb-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("clover_folktale/imdb-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 '{}' |
apify call clover_folktale/imdb-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_folktale/imdb-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 <APIFY_API_TOKEN>` 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/hwztqiIhPd4ezxy67/builds/zgWyg39nR5eiozHAM/openapi.json