# IMDb Top Charts & Advanced Title Search (`nimbryxo-studio/imdb-top-charts-and-advanced-title-search`) Actor

Search IMDb movies and TV shows, fetch titles by IMDb ID, browse Top 250 and regional charts, or run an advanced search by genre, year, rating and vote count, with cast, crew and plot details per title.

- **URL**: https://apify.com/nimbryxo-studio/imdb-top-charts-and-advanced-title-search.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Videos, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 Search, Charts, Reviews & Episodes Scraper

IMDb spreads search, charts, title details, user reviews and episode lists across separate pages with no bulk export. This actor collects them into one dataset: search results, direct title lookups, nine official charts, the popularity meter, filtered advanced searches, user reviews, and episode lists for TV series — each row carrying the metadata IMDb publishes for it.

### What this actor does

- Searches IMDb's full title catalog by keyword, with optional type, genre, year, rating and vote filters
- Fetches specific titles directly by IMDb ID or title URL
- Pulls one of nine IMDb charts, including Top 250, Top 250 TV, Bottom 100, English-language and regional Indian charts
- Returns IMDb's current popularity-meter titles
- Runs a filtered, sortable advanced search by title type, genre, country, language, runtime, release year, minimum rating and minimum vote count
- Exports user reviews with reviewer name, reviewer rating, review title and body, helpfulness votes, spoiler flag and submission date
- Lists episodes of a TV series with season and episode numbers, episode rating, plot, runtime, certificate, poster and credits
- Enriches title rows with rating breakdown, keywords, production companies, alternative titles (AKAs), detailed release dates, trailers, awards, box office (including worldwide gross) and popularity rank
- Omits a field when IMDb did not publish a value for it

### One dataset, three row types

Every row has a `recordType`:

| `recordType` | What the row represents |
|---|---|
| `title` | A movie, TV series, short, video game or other title |
| `review` | One IMDb user review of a title |
| `episode` | One episode of a TV series |

#### Title row fields

| Field | Description |
|---|---|
| `recordType` | `title` |
| `imdbId` | IMDb title ID, e.g. `tt0111161` |
| `title` | Display title |
| `originalTitle` | Original-language title, when different from `title` |
| `type` | Title type, e.g. `movie`, `tvSeries`, `tvEpisode` |
| `year` | Release year |
| `endYear` | Final year on air, for ended TV series |
| `rating` | IMDb rating out of 10 |
| `ratingCount` | Number of ratings behind the score |
| `metascore` | Metacritic score, when IMDb has one |
| `ratingBreakdown` | Vote counts per score: list of `{ rating, voteCount }` from 1 to 10 |
| `plot` | Plot summary |
| `genres` | List of genres |
| `runtime` | Runtime in minutes |
| `certificate` | Content/age rating certificate |
| `posterUrl` | Poster image URL |
| `releaseDate` | Primary release date, when more precise than the year |
| `releaseDates` | Detailed release dates: list of `{ date, country }` |
| `countries` | Countries of origin |
| `languages` | Spoken languages |
| `directors` | Up to 5 directors, each `{ name, imdbId }` |
| `writers` | Up to 5 writers, each `{ name, imdbId }` |
| `cast` | Up to 10 cast members, each `{ name, imdbId, character }` |
| `keywords` | Up to 10 plot keywords |
| `companies` | Up to 10 production/distribution credits, each `{ name, companyId, category }` |
| `akas` | Up to 10 alternative titles, each `{ title, country, countryCode, language }` |
| `trailers` | Up to 50 trailers/clips, each `{ videoId, url, title, type, thumbnailUrl, runtimeSeconds }` |
| `budget` | Production budget as `{ amount, currency }`, when IMDb publishes one |
| `domesticLifetimeGross` | Domestic lifetime gross as `{ amount, currency }` |
| `internationalLifetimeGross` | International lifetime gross as `{ amount, currency }` |
| `worldwideLifetimeGross` | Worldwide lifetime gross as `{ amount, currency }` |
| `openingWeekend` | `{ date, theaters, gross: { amount, currency } }` for the domestic opening weekend |
| `internationalOpeningWeekend` | `{ date, theaters, gross: { amount, currency } }` for the international opening weekend |
| `awards` | Total competitive `{ wins, nominations }` |
| `prestigiousAwards` | Major-award summary `{ wins, nominations }` (for example Oscars) |
| `popularityRank` | Current IMDb popularity-meter position |
| `imdbUrl` | Link to the title's IMDb page |
| `sourceUrl` | Same as `imdbUrl` for title rows |
| `topRatedRank` | Chart position, present only on chart rows |
| `scrapedAt` | UTC timestamp of when the row was captured |

#### Review row fields

| Field | Description |
|---|---|
| `recordType` | `review` |
| `imdbId` | IMDb ID of the reviewed title |
| `title` | Title name |
| `type` | Title type |
| `year` | Title release year |
| `imdbUrl` | Link to the title's IMDb page |
| `reviewId` | IMDb review ID, e.g. `rw6606154` |
| `reviewTitle` | Review headline |
| `reviewText` | Full review body |
| `author` | Reviewer display name |
| `authorId` | Reviewer profile ID |
| `authorRating` | Rating the reviewer gave the title (1–10), when supplied |
| `submissionDate` | Review submission date |
| `helpfulUpVotes` | Helpful votes received |
| `helpfulDownVotes` | Not-helpful votes received |
| `spoiler` | `true` when the review is flagged as containing spoilers |
| `reviewUrl` | Link to the review on IMDb |
| `sourceUrl` | Same as `reviewUrl` for review rows |
| `scrapedAt` | UTC timestamp of when the row was captured |

#### Episode row fields

| Field | Description |
|---|---|
| `recordType` | `episode` |
| `imdbId` | IMDb ID of the episode itself |
| `title` | Episode title |
| `originalTitle` | Original-language episode title, when different |
| `type` | `tvEpisode` |
| `year` | Episode release year |
| `rating` | Episode IMDb rating |
| `ratingCount` | Number of episode ratings |
| `metascore` | Episode Metacritic score, when IMDb has one |
| `ratingBreakdown` | Vote counts per score: list of `{ rating, voteCount }` |
| `plot` | Episode plot summary |
| `genres` | Episode genres |
| `runtime` | Episode runtime in minutes |
| `certificate` | Episode content rating |
| `posterUrl` | Episode image URL |
| `releaseDate` | Episode release date |
| `countries` | Countries of origin |
| `languages` | Spoken languages |
| `directors` / `writers` / `cast` | Episode credits |
| `popularityRank` | Current IMDb popularity-meter position |
| `seriesId` | IMDb ID of the parent series |
| `seriesTitle` | Parent series name |
| `seriesUrl` | Link to the parent series |
| `seasonNumber` | Season number |
| `episodeNumber` | Episode number within the season |
| `imdbUrl` | Link to the episode's IMDb page |
| `sourceUrl` | Same as `imdbUrl` for episode rows |
| `scrapedAt` | UTC timestamp of when the row was captured |

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string (select) | `topRated` | `topRated`, `search`, `byId`, `popular`, `advanced`, `reviews`, or `episodes` |
| `searchQuery` | string | – | Free-text title query (mode `search`) |
| `imdbIds` | array | `[]` | IMDb title IDs or URLs for `byId`, `reviews`, and `episodes` modes |
| `reviewSortBy` | string (select) | `HELPFULNESS_SCORE` | Review ordering: `HELPFULNESS_SCORE`, `USER_RATING`, `SUBMISSION_DATE`, or `TOTAL_VOTES` |
| `reviewSortOrder` | string (select) | `DESC` | `DESC` or `ASC` |
| `excludeSpoilers` | boolean | `false` | Skip reviews flagged as spoilers |
| `topRatedChart` | string (select) | `TOP_250` | Which chart to fetch (mode `topRated`) — see chart list below |
| `titleType` | string (select) | – (all types) | `movie`, `tvSeries`, `short`, `tvMiniSeries`, `tvMovie`, `tvSpecial`, `videoGame`, or `podcastSeries` |
| `genres` | array | `[]` | Genres to filter by (combined with AND); e.g. `Drama`, `Thriller`, `Sci-Fi` |
| `languages` | array | `[]` | Spoken-language codes to filter by (combined with OR); e.g. `en`, `fr`, `hi`, `ta` |
| `countries` | array | `[]` | Country-of-origin codes to filter by (combined with OR); e.g. `US`, `GB`, `IN`, `JP` |
| `runtimeMin` / `runtimeMax` | integer | – | Runtime range in minutes (1–1440) |
| `yearMin` / `yearMax` | integer | – | Release year range (1880–2030) |
| `minRating` | number | – | Minimum IMDb rating (1–10) |
| `minVotes` | integer | – | Minimum vote count |
| `sortBy` | string (select) | `RANKING` | `RANKING`, `USER_RATING`, `USER_RATING_COUNT`, `RELEASE_DATE`, `TITLE_REGIONAL`, or `METACRITIC_SCORE` |
| `sortOrder` | string (select) | `DESC` | `DESC` or `ASC` |
| `maxItems` | integer | 50 | Maximum records to return (1–1000). Reviews and episodes are one record each |

### Examples

#### Top 250 movies

```json
{
  "mode": "topRated",
  "topRatedChart": "TOP_250",
  "maxItems": 50
}
```

#### Search for a title

```json
{
  "mode": "search",
  "searchQuery": "The Dark Knight",
  "maxItems": 10
}
```

#### Fetch specific titles by ID

```json
{
  "mode": "byId",
  "imdbIds": ["tt0111161", "tt0468569", "tt1375666"]
}
```

#### Advanced search for recent, well-voted sci-fi

```json
{
  "mode": "advanced",
  "titleType": "movie",
  "genres": ["Sci-Fi"],
  "yearMin": 2010,
  "minRating": 7.5,
  "minVotes": 50000,
  "sortBy": "USER_RATING",
  "sortOrder": "DESC",
  "maxItems": 100
}
```

#### Advanced search by country, language and runtime

```json
{
  "mode": "advanced",
  "titleType": "movie",
  "countries": ["IN"],
  "languages": ["ta"],
  "runtimeMin": 90,
  "runtimeMax": 180,
  "sortBy": "USER_RATING",
  "maxItems": 50
}
```

#### Export reviews for two titles

```json
{
  "mode": "reviews",
  "imdbIds": ["tt0111161", "tt0468569"],
  "reviewSortBy": "HELPFULNESS_SCORE",
  "reviewSortOrder": "DESC",
  "excludeSpoilers": true,
  "maxItems": 100
}
```

#### List every episode of a series

```json
{
  "mode": "episodes",
  "imdbIds": ["tt0903747"],
  "maxItems": 100
}
```

#### Current popularity meter

```json
{
  "mode": "popular",
  "maxItems": 50
}
```

### Available chart types

| Value | Description |
|---|---|
| `TOP_250` | Top 250 movies of all time |
| `TOP_250_ENGLISH` | Top 250 English-language movies |
| `TOP_250_TV` | Top 250 TV series |
| `BOTTOM_100` | Bottom 100 lowest-rated movies |
| `TOP_50_BENGALI` | Top 50 Bengali-language films |
| `TOP_50_MALAYALAM` | Top 50 Malayalam-language films |
| `TOP_50_TAMIL` | Top 50 Tamil-language films |
| `TOP_50_TELUGU` | Top 50 Telugu-language films |
| `TOP_250_INDIA` | Top 250 Indian films overall |

### Use cases

- **Recommendation engines** — export a chart with ratings, genres, keywords and rating breakdowns to seed a model
- **Catalog enrichment** — fetch metadata for a known list of IMDb IDs and fill in cast, companies, AKAs, release dates and box office including worldwide gross
- **Review analysis** — export reviews with reviewer ratings, helpfulness votes and spoiler flags for sentiment or topic research
- **TV episode guides** — list every episode of a series with season/episode numbers, ratings, plots and credits
- **Genre, language and era research** — run a filtered advanced search by genre, country, language, runtime, year or vote level to study which titles rate highest
- **Watchlist building** — combine type, genre, rating and vote filters to find well-reviewed titles you have missed
- **Regional content discovery** — pull a language-specific chart like Tamil or Malayalam alongside the global Top 250
- **Awards and box office research** — compare wins, nominations, budgets, domestic/international/worldwide grosses and opening weekends

### FAQ

**Is this affiliated with IMDb?**
No. This is an independent data extraction tool and has no connection to IMDb.com or Amazon.

**Do I need an IMDb account or API key?**
No — nothing needs to be configured beyond the mode and filters above.

**How fresh is the data?**
Each run reads IMDb's current data at the time it executes, so ratings, vote counts and chart positions reflect that moment.

**How many reviews can I export?**
`maxItems` caps the total rows per run (up to 1000). When you pass several IMDb IDs, the budget is shared across them. Reviews are paginated 50 at a time, so titles with many reviews can fill large exports. Sort and spoiler filters apply to every requested title.

**Why do some reviews have no `authorRating`?**
IMDb allows reviewers to submit text without a numeric score; those reviews simply omit the field.

**Why does episodes mode return nothing?**
Episodes mode expects TV series IDs. A movie ID has no episode list. Try a series such as `tt0903747`.

**Can I get individual TV episode records?**
Yes — use episodes mode with the series ID. You can also fetch a known episode ID directly with `byId`.

**Why are some titles missing box office, awards or trailers?**
IMDb does not publish every field for every title. Box office is a theatrical-film field, so TV series and streaming titles normally have none; older, regional or obscure releases may also lack it. The actor leaves those fields out instead of guessing.

**Why is the cast list capped?**
To keep rows a manageable size while covering the top-billed cast, which is the most commonly needed slice. Episode rows use the same cast cap.

**Are trailer playback URLs included?**
No. Trailer rows include a stable IMDb video page URL, title, type, thumbnail and runtime, not expiring video-file links.

**What is `popularityRank`?**
It is the title's current position on IMDb's popularity meter; lower numbers mean more popular.

**What is the difference between `topRated` and `advanced`?**
`topRated` returns one of IMDb's fixed chart lists in chart order; `advanced` runs a filtered, sortable search across IMDb's full catalog using the criteria you specify.

**How do I find a title's IMDb ID?**
It is in the title's IMDb page URL, e.g. `imdb.com/title/tt0111161/` — pass it with or without the `tt` prefix, or paste the full URL.

**Can I mix title, review and episode rows in one run?**
Each run uses one mode and produces one row type, except that `byId` can return any title-shaped record. Use the `recordType` field when combining exports from several runs.

# Actor input Schema

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

What to fetch from IMDb: title search, direct IDs, a chart, the popularity meter, a filtered search, user reviews, or TV episodes.

## `searchQuery` (type: `string`):

Free-text title search, e.g. 'inception' or 'breaking bad'. Used in search mode.

## `imdbIds` (type: `array`):

IMDb title IDs (e.g. tt0111161) or title URLs. Used by byId, reviews and episodes modes. In episodes mode, pass TV series IDs.

## `reviewSortBy` (type: `string`):

How to order reviews in reviews mode.

## `reviewSortOrder` (type: `string`):

Ascending or descending order for the review sort.

## `excludeSpoilers` (type: `boolean`):

Skip reviews flagged as containing spoilers.

## `titleType` (type: `string`):

Restrict results to one content type. Used in search, popular and advanced modes.

## `genres` (type: `array`):

Filter by genres, e.g. Drama, Thriller, Sci-Fi. Multiple genres are combined with AND. Used in search and advanced modes.

## `languages` (type: `array`):

Filter by spoken-language codes, e.g. en, fr, hi, ta. Multiple languages are combined with OR. Used in search and advanced modes.

## `countries` (type: `array`):

Filter by country-of-origin codes, e.g. US, GB, IN, JP. Multiple countries are combined with OR. Used in search and advanced modes.

## `runtimeMin` (type: `integer`):

Only include titles at least this many minutes long. Used in search and advanced modes.

## `runtimeMax` (type: `integer`):

Only include titles at most this many minutes long. Used in search and advanced modes.

## `yearMin` (type: `integer`):

Include only titles released on or after this year.

## `yearMax` (type: `integer`):

Include only titles released on or before this year.

## `minRating` (type: `number`):

Only include titles with at least this IMDb rating (1-10).

## `minVotes` (type: `integer`):

Only include titles with at least this many IMDb votes.

## `sortBy` (type: `string`):

Sort field for search and advanced modes.

## `sortOrder` (type: `string`):

Sort direction for search and advanced modes.

## `topRatedChart` (type: `string`):

Which IMDb chart to fetch in topRated mode.

## `maxItems` (type: `integer`):

Maximum number of records to return across all requested IDs (1-1000). Each review or episode is one record. Results are paginated, so the upstream 50-reviews-per-request limit does not cap this.

## Actor input object example

```json
{
  "mode": "topRated",
  "searchQuery": "inception",
  "imdbIds": [],
  "reviewSortBy": "HELPFULNESS_SCORE",
  "reviewSortOrder": "DESC",
  "excludeSpoilers": false,
  "titleType": "",
  "genres": [],
  "languages": [],
  "countries": [],
  "sortBy": "RANKING",
  "sortOrder": "DESC",
  "topRatedChart": "TOP_250",
  "maxItems": 3
}
```

# Actor output Schema

## `titles` (type: `string`):

Dataset containing title, review and episode records.

# 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 = {
    "mode": "topRated",
    "searchQuery": "inception",
    "imdbIds": [],
    "reviewSortBy": "HELPFULNESS_SCORE",
    "reviewSortOrder": "DESC",
    "excludeSpoilers": false,
    "titleType": "",
    "genres": [],
    "languages": [],
    "countries": [],
    "sortBy": "RANKING",
    "sortOrder": "DESC",
    "topRatedChart": "TOP_250",
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/imdb-top-charts-and-advanced-title-search").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 = {
    "mode": "topRated",
    "searchQuery": "inception",
    "imdbIds": [],
    "reviewSortBy": "HELPFULNESS_SCORE",
    "reviewSortOrder": "DESC",
    "excludeSpoilers": False,
    "titleType": "",
    "genres": [],
    "languages": [],
    "countries": [],
    "sortBy": "RANKING",
    "sortOrder": "DESC",
    "topRatedChart": "TOP_250",
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/imdb-top-charts-and-advanced-title-search").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 '{
  "mode": "topRated",
  "searchQuery": "inception",
  "imdbIds": [],
  "reviewSortBy": "HELPFULNESS_SCORE",
  "reviewSortOrder": "DESC",
  "excludeSpoilers": false,
  "titleType": "",
  "genres": [],
  "languages": [],
  "countries": [],
  "sortBy": "RANKING",
  "sortOrder": "DESC",
  "topRatedChart": "TOP_250",
  "maxItems": 3
}' |
apify call nimbryxo-studio/imdb-top-charts-and-advanced-title-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/imdb-top-charts-and-advanced-title-search"
        }
    }
}
```

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/vCwUhfrZSJ6ZgYDhE/builds/Fbeq026cct90fLKAG/openapi.json