# IMDB Ratings (`bebich/imdb-ratings`) Actor

Download movie data and ratings from biggest Movie database.

- **URL**: https://apify.com/bebich/imdb-ratings.md
- **Developed by:** [ALi](https://apify.com/bebich) (community)
- **Categories:** Videos
- **Stats:** 42 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## IMDB - Movie data and ratings scraper

This actor can scrape movie [info](https://www.imdb.com/title/tt10954600/) and movie ratings from [page](https://www.imdb.com/title/tt10954600/ratings/).

### Actor cost

Actor using cheerio scraper which is efficient. Recommended RAM usage is 256MB.

### Input config

1. Choose what you want scrape: `specific title IDs (MOVIE_IDS)` or `search keyword (QUERY) (limited to 5 titles per search)` or `scrape IMDB chart (CHART)`.
2. If you set CHART. You can set `LIMIT` and `START_LIMIT_FROM` (optional)
3. Do you want scrape title data `GET_MOVIES_DATA`, ratings `GET_RATINGS` or IDs `SAVE_IDs`?
4. Do you want save data to named dataset to have specific data in named dataset? Than set `DATASET_NAME` or `DATASET_NAME_RATINGS` or `DATASET_NAME_ID`

### Input

|Inpot value|Description|Example|
|---|---|---|
|MOVIE\_IDS|Scrape list of IDs from IMDB. ID can be find in url: https://www.imdb.com/title/tt10954600/|`tt10954600`|
|QUERY|Search any keyword. It's limited to only 5 titles per search|"Star Wars"|
|CHART|Scrape any IMDB chart. Like popular chart.|`moviemeter`|
|START\_LIMIT\_FROM (optional)|Starting number of scraping movies. Default value is 1|`1`|
|LIMIT (optional)|Maximum number of movies that will be scraped. Default value is 50|`500`|
|GET\_MOVIES\_DATA|Set `true` if you want scrape movie data|`true` or `false`|
|GET\_RATINGS|Set `true` if you want scrape ratings|`true` or `false`|
|SAVE\_IDs (optional)|Set `true` if you want scrape IDs. Only for `QUERY` or `CHART`|`true` or `false`|
|DATASET\_NAME (optional)|Save scraped data to named dataset. Run actor many times with same name but different IDs than this dataset will contains all data.|`EXAMPLE_NAME`|
|DATASET\_NAME\_RATINGS (optional)|Save scraped ratings to named dataset.|`EXAMPLE_RATING`|
|DATASET\_NAME\_ID (optional)|Save scraped IDs to named dataset.|`EXAMPLE_ID`|
|CLEAN\_DATASET\_NAMES (optional)|Array of dataset name(s) which will be deleted first.|\["EXAMPLE\_NAME","EXAMPLE\_RATING","EXAMPLE\_ID"]|
|proxyConfiguration (optional)|Select proxy to avoid IP address blocking.||

#### Input example

Scrape ratings for 3 movies:

```
{
  "MOVIE_IDS": ["tt10954600", "tt12823454", "tt2911666"],
  "GET_RATINGS": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

Scrape 5 movie data from search keyword "John Wick":

```
{
  "QUERY": "John Wick",
  "GET_MOVIES_DATA": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

#### Charts

IMDB has different chart.
Just set: `{ "CHART": "moviemeter", }`

|CHART|value|
|---|---|
|Popularity|"moviemeter"|
|A-Z|"alpha"|
|User Rating|"user\_rating"|
|Number of Votes|"num\_votes"|
|US Box Office|"boxoffice\_gross\_us"|
|Runtime|"runtime"|
|Year|"year"|
|Release Date|"release\_date"|
|Date of Your Rating|"your\_rating\_date"|
|Your Rating|"sort=my\_ratings"|

#### Result for MOVIE DATA

Input:
`{ "GET_MOVIES_DATA": true }`

```
{
	"id": "tt2911666",
	"title": "John Wick",
	"releaseDate": "October 24, 2014 (United States)",
	"director": [
		"Chad Stahelski",
		"David Leitch"
	],
	"writers": [
		"Derek Kolstad"
	],
	"countryOfOrigin": [
		"United States",
		"United Kingdom",
		"China"
	],
	"rating": "7.4",
	"popularity": "119",
	"genres": [
		"Action",
		"Crime",
		"Thriller"
	],
	"officialSites": [
		"http://www.facebook.com/johnwickmovie",
		"http://www.johnwickthemovie.com/"
	],
	"language": "EnglishRussianHungarian",
	"locations": [
		"Calvary Cemetery, Woodside, Queens, New York City, New York, USA"
	],
	"ProductionCompanies": [
		"Summit Entertainment",
		"Thunder Road Pictures",
		"87Eleven"
	],
	"grossUSCanada": "$43,037,835",
	"openingWeekendUSCanada": "$14,415,922",
	"grossWorldwide": "$86,081,711",
	"runtime": "1 hour 41 minutes",
	"casts": [
		"Keanu Reeves @ John Wick",
		"Michael Nyqvist @ Viggo Tarasov",
		"Alfie Allen @ Iosef Tarasov",
		"Willem Dafoe @ Marcus",
		"Dean Winters @ Avi",
		"Adrianne Palicki @ Ms. Perkins",
		"Omer Barnea @ Gregori",
		"Toby Leonard Moore @ Victor",
		"Daniel Bernhardt @ Kirill",
		"Bridget Moynahan @ Helen",
		"John Leguizamo @ Aurelio",
		"Ian McShane @ Winston",
		"Bridget Regan @ Addy",
		"Lance Reddick @ Hotel Manager",
		"Keith Jardine @ Kuzma",
		"Tait Fletcher @ Nicholai",
		"Kazy Tauginas @ Ivan",
		"Alexander Frekey @ Alexander"
	],
	"url": "https://www.imdb.com/title/tt2911666"
}
```

#### Result for ID's

Input:
`{ "SAVE_IDs": true }`

```
{
	"url": "https://www.imdb.com/find/?q=John+Wick",
	"titles": [
		{
			"title": "John Wick: Chapter 4",
			"id": "tt10366206"
		},
		{
			"title": "John Wick",
			"id": "tt2911666"
		},
		{
			"title": "John Wick: Chapter 2",
			"id": "tt4425200"
		},
		{
			"title": "John Wick: Chapter 3 - Parabellum",
			"id": "tt6146586"
		},
		{
			"title": "John Wick: Chapter 5",
			"id": "tt12844100"
		}
	]
}
```

#### Result for ratings

Input:
`{ "GET_RATINGS": true }`

- Return ratings for all demographics:

`'imdb_users', 'males', 'females', 'aged_under_18', 'aged_18_29', 'aged_30_44', 'aged_45_plus', 'males_aged_under_18', 'males_aged_18_29', 'males_aged_30_44', 'males_aged_45_plus', 'females_aged_under_18', 'females_aged_18_29', 'females_aged_30_44', 'females_aged_45_plus'`

For all IMDB users:

```
{
	"date": "22-02-2023",
	"title": "John Wick (2014)",
	"demographic": "imdb_users",
	"averageVote": 7.4,
	"arithmeticVote": 7.6,
	"medianVote": 8,
	"totalVotes": 645487,
	"Votes_10": 79402,
	"Percent_10": 12.3,
	"Votes_9": 87601,
	"Percent_9": 13.6,
	"Votes_8": 188132,
	"Percent_8": 29.1,
	"Votes_7": 171542,
	"Percent_7": 26.6,
	"Votes_6": 68794,
	"Percent_6": 10.7,
	"Votes_5": 25724,
	"Percent_5": 4,
	"Votes_4": 10195,
	"Percent_4": 1.6,
	"Votes_3": 5509,
	"Percent_3": 0.9,
	"Votes_2": 3443,
	"Percent_2": 0.5,
	"Votes_1": 5145,
	"Percent_1": 0.8,
	"url": "https://www.imdb.com/title/tt2911666/ratings?demo=imdb_users"
}
```

# Actor input Schema

## `MOVIE_IDS` (type: `array`):

Array of movie IDs which wil be scraped. Example: \['tt2527338', 'tt1490017']

## `QUERY` (type: `string`):

Search query. It will save 5 IDs which can be scraped. Example: 'John Wick' or 'Star Wars'

## `CHART` (type: `string`):

Save IDs, scrape info or ratings from IMDB charts. Popular movies example: 'moviemeter'

## `START_LIMIT_FROM` (type: `integer`):

Starting limit number for scraping charts. Default is 1. Set 100 and than it will scrape from 100.movie in IMDb Charts (example popular).

## `LIMIT` (type: `integer`):

Scraping limit number for IMDb Charts (popular). Default is 50.

## `GET_MOVIES_DATA` (type: `boolean`):

If checked it will scrape movie data.

## `DATASET_NAME` (type: `string`):

Save movie data to named dataset.

## `GET_RATINGS` (type: `boolean`):

If checked it will scrape movie ratings.

## `DATASET_NAME_RATINGS` (type: `string`):

Save movie ratings to named dataset.

## `SAVE_IDs` (type: `boolean`):

If checked it will save IDs

## `DATASET_NAME_ID` (type: `string`):

Save movie IDs to named dataset.

## `CLEAN_DATASET_NAMES` (type: `array`):

Array of dataset name(s) which data will be deleted before scraping

## `proxyConfiguration` (type: `object`):

Specifies proxy servers that will be used by the scraper in order to hide its origin.<br><br>For details, see <a href='https://apify.com/apify/web-scraper#proxy-configuration' target='_blank' rel='noopener'>Proxy configuration</a> in README.

## Actor input object example

```json
{
  "MOVIE_IDS": [
    "tt0111161"
  ],
  "START_LIMIT_FROM": 1,
  "LIMIT": 50,
  "GET_MOVIES_DATA": false,
  "GET_RATINGS": true,
  "SAVE_IDs": false,
  "CLEAN_DATASET_NAMES": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "MOVIE_IDS": [
        "tt0111161"
    ],
    "QUERY": "",
    "CHART": "",
    "DATASET_NAME": "",
    "DATASET_NAME_RATINGS": "",
    "DATASET_NAME_ID": "",
    "CLEAN_DATASET_NAMES": [],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("bebich/imdb-ratings").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 = {
    "MOVIE_IDS": ["tt0111161"],
    "QUERY": "",
    "CHART": "",
    "DATASET_NAME": "",
    "DATASET_NAME_RATINGS": "",
    "DATASET_NAME_ID": "",
    "CLEAN_DATASET_NAMES": [],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("bebich/imdb-ratings").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 '{
  "MOVIE_IDS": [
    "tt0111161"
  ],
  "QUERY": "",
  "CHART": "",
  "DATASET_NAME": "",
  "DATASET_NAME_RATINGS": "",
  "DATASET_NAME_ID": "",
  "CLEAN_DATASET_NAMES": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call bebich/imdb-ratings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bebich/imdb-ratings"
        }
    }
}

```

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/sAUdXRnohhJY9aOiA/builds/t7VgU1Kxod1bTOGeE/openapi.json