# TMDB Scraper - Movies, TV Shows, Ratings & Trending (`automly/tmdb-movie-tv-api`) Actor

Search movies, TV shows and people on The Movie Database (TMDB) with your own free TMDB key: titles, ratings, vote counts, overviews, posters, release dates and trending titles. Export to CSV, JSON or Excel, schedule runs or use the API.

- **URL**: https://apify.com/automly/tmdb-movie-tv-api.md
- **Developed by:** [Automly](https://apify.com/automly) (community)
- **Categories:** Videos, Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / 1,000 result item produceds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## TMDB Scraper - Movies, TV Shows, Ratings & Trending

### What is TMDB Scraper?

**TMDB Scraper** is a tool that lets you **scrape movies, TV shows and people from The Movie Database (TMDB)**: title, original title, overview, poster and backdrop images, release or first-air date, rating, vote count, popularity and genres. Search by title, browse by genre and year, or get this week's trending titles. Add your free TMDB API key, click **Start**, and download the results as Excel, CSV or JSON.

This product uses the TMDB API but is not endorsed or certified by TMDB.

- 🎬 **Three ways in:** search by title or name, discover by genre, year and sort order, or this week's trending
- 🖼️ **Ready-to-use images:** poster, backdrop and profile image links
- 🌍 **Your language:** titles and overviews in en-US, de-DE, fr-FR, ja-JP and more
- 💸 **Free to try:** the $5 of free usage every Apify account gets each month covers about 10,000 movies, shows or people

### What can TMDB Scraper do?

- Search TMDB movies by title
- Search TMDB TV shows and people by name, or all three at once
- Find movies by genre and release year, such as action movies of 2024
- Get the best-rated movies by genre, sorted by rating, popularity, release date or revenue
- Get this week's trending movies, TV shows and people on TMDB
- Get movie poster and backdrop image links
- Get movie and TV titles and overviews in another language
- Export TMDB data to Excel, CSV, JSON, HTML or XML

### What data can you extract from TMDB?

| | | |
|---|---|---|
| 🎬 Title and original title | 📝 Overview | 🆔 TMDB ID |
| ⭐ Rating (vote average) | 🗳️ Vote count | 📈 Popularity |
| 📅 Release or first-air date | 🏷️ Genre IDs | 🌐 Language code |
| 🖼️ Poster image | 🌄 Backdrop image | 🔞 Adult flag |
| 🌍 Origin country (TV) | 👤 Known-for titles (people) | 📸 Profile image (people) |

### Before you start: get your free TMDB key

1. Create a free account at [themoviedb.org](https://www.themoviedb.org/signup).
2. Open **Settings > API** ([themoviedb.org/settings/api](https://www.themoviedb.org/settings/api)) and request an API key (choose the developer option and fill in the short form).
3. Copy either of the two keys on that page: the short **API Key** or the long **API Read Access** code. Both work.
4. Paste it into the **TMDB API Key** field of this actor. Apify stores it encrypted.

TMDB's own terms apply to your use of its data; read them on the same settings page.

### How to scrape TMDB movies and TV shows

1. [Create a free Apify account](https://console.apify.com/sign-up) (no credit card needed).
2. Open **TMDB Scraper** and paste your **TMDB API Key**.
3. Pick a **Search Type**: search (movies, TV, people or all), discover, or trending.
4. Type a **Search Query** for the search types, or set **Genre**, **Release Year** and **Sort By** for discover. Set **Max Results** and click **Start**.
5. When the run finishes, open the **Titles** view (movies and shows) or the **People** view in the **Output** tab, or download the results as Excel, CSV, JSON, HTML or XML.

### How much does it cost to scrape TMDB?

You pay **$0.50 per 1,000 results** (each movie, TV show or person is one result). Apify platform usage is included in this price, so there is nothing else to pay for the run. TMDB does not charge for its API key.

For example, 1,000 movies cost $0.50 on the Free plan, and a search that returns 20 results costs $0.01.

Every Apify account gets **$5 of free usage each month**. See the **Pricing** tab for details.

### ⬇️ Input

| Setting | What it does |
|---|---|
| TMDB API Key | Your free TMDB API Key or long read access code (required) |
| Search Type | `multi` (movies, TV and people), `movie`, `tv`, `person`, `discover` or `trending` |
| Search Query | Title or name, for the search types |
| Release Year | Four-digit year (first-air year for TV), for movie and TV search and for discover |
| Genre | Genre name, for discover, such as `Action` or `Sci-Fi & Fantasy` |
| Language | Language of titles and overviews (default `en-US`) |
| Sort By | Sort for discover: popularity, rating, release date or revenue, up or down |
| Max Results | How many results to return (default 20, up to 100) |
| Include Adult Content | Include adult titles (off by default) |

Example: search everything for a title.

```json
{
  "apiKey": "YOUR_TMDB_API_KEY",
  "searchType": "multi",
  "query": "Inception",
  "maxResults": 20
}
```

Example: best-rated action movies of 2024.

```json
{
  "apiKey": "YOUR_TMDB_API_KEY",
  "searchType": "discover",
  "genre": "Action",
  "year": "2024",
  "sortBy": "vote_average.desc",
  "maxResults": 50
}
```

Example: this week's trending titles, in German.

```json
{
  "apiKey": "YOUR_TMDB_API_KEY",
  "searchType": "trending",
  "language": "de-DE",
  "maxResults": 100
}
```

### ⬆️ Output

You get one row per movie, TV show or person. `mediaType` tells them apart. You can view the rows as a table in Apify Console or download them as Excel, CSV, JSON, HTML or XML.

```json
{
  "itemId": 27205,
  "mediaType": "movie",
  "title": "Inception",
  "originalTitle": "Inception",
  "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another person's idea into a target's subconscious.",
  "posterUrl": "https://image.tmdb.org/t/p/w500/qzb0slJerd5bQgJxteJ5oAmfp09.jpg",
  "backdropUrl": "https://image.tmdb.org/t/p/w500/8ZTVqvKDQ8emSGUEMjsS4yHAwrp.jpg",
  "popularity": 112.45,
  "voteAverage": 8.364,
  "voteCount": 37140,
  "language": "en",
  "releaseDate": "2010-07-15",
  "adult": false,
  "genreIds": [28, 878, 12]
}
```

TV shows carry `firstAirDate` and `originCountry` instead of `releaseDate`; people carry `knownFor`, `knownForTitles` and `profileUrl`.

### How can I use TMDB data?

- **Movie and TV apps:** build catalogs, watchlists and recommendation lists with posters and ratings
- **Data enrichment:** add posters, ratings and release dates to your own list of titles
- **Trend tracking:** see what is trending this week for content, marketing or research
- **Datasets:** build lists of films and shows by genre and year for analysis
- **Localized catalogs:** get titles and overviews in your audience's language

### Scrape more entertainment and knowledge data

| Actor | What it gets |
|---|---|
| [YouTube Search Scraper - Videos, Channels & Playlists](https://apify.com/automly/youtube-search-results-scraper) | YouTube search results, such as trailers and reviews, with views, durations and upload dates |
| [YouTube Channel Scraper - Search Channels by Keyword](https://apify.com/automly/youtube-channel-search-scraper) | YouTube channels by keyword with subscribers, video and view counts |
| [Wikidata Scraper - Entities, Labels & Descriptions](https://apify.com/automly/wikidata-entity-api) | Wikidata entities for films, people and studios, with labels, descriptions and Wikipedia links |
| [Reddit Scraper - Posts, Comments, Users, Subreddits & Search](https://apify.com/automly/reddit-ultimate-scraper) | Reddit posts and comments, such as movie and TV discussions |
| [Google News Scraper - Full Article Text, Alerts & RSS](https://apify.com/automly/google-news-scraper-api) | Google News articles by keyword with full text |

### ❓FAQ

#### How much does TMDB Scraper cost?

$0.50 per 1,000 movies, TV shows or people, platform usage included. See the cost section above and the **Pricing** tab.

#### Do I need a TMDB account?

Yes. TMDB gives every developer a free personal API key and asks that requests are made with it. Creating the account and key is free and takes a few minutes (see **Before you start** above). Your key stays yours and is stored encrypted.

#### My run failed with "TMDB rejected the API key"?

Copy the key again from [themoviedb.org/settings/api](https://www.themoviedb.org/settings/api). Either the API Key (32 characters) or the long read access code (starting with `eyJ`) works.

#### How many results can I get per run?

Up to 100 per run. For more, run several searches, for example one per genre or year.

#### Which genres can I use?

TMDB's genre names, such as Action, Adventure, Animation, Comedy, Crime, Documentary, Drama, Family, Fantasy, History, Horror, Music, Mystery, Romance, Science Fiction, Thriller, War and Western for movies, and Action & Adventure, Kids, News, Reality, Sci-Fi & Fantasy, Soap, Talk and War & Politics for TV. A name TMDB does not know stops the run with the list of valid names.

#### Can I get full details such as cast, runtime or budget?

Not with this actor. It returns the search, discover and trending results with the fields above.

#### How fresh is the data?

Each run reads TMDB live. Trending covers the current week.

#### Can I connect TMDB Scraper to other tools or AI agents?

Yes. Start runs and download results with the Apify API or the Python and JavaScript clients, send results to Make, Zapier, n8n, Google Sheets or Slack with Apify integrations and webhooks, or let AI assistants and agents run it through the Apify MCP server at [mcp.apify.com](https://mcp.apify.com).

#### Is it legal to scrape TMDB?

This actor reads TMDB with your own free API key, under TMDB's terms of use, which you accept when you create the key. It only returns public catalog data. People results can still contain personal data, which may be protected by laws such as GDPR, so only use it for a legitimate reason and ask a lawyer if you are unsure. You can read more in [Is web scraping legal?](https://blog.apify.com/is-web-scraping-legal/)

TMDB Scraper is an independent tool. It is not affiliated with, endorsed by or sponsored by TMDB (The Movie Database).

#### Something isn't working?

Open the **Issues** tab and tell us your input (without your key) and what you expected.

### ⭐ Your feedback

Have an idea or found a problem? Tell us on the **Issues** tab. If TMDB Scraper saved you time, a short review on the **Reviews** tab helps other people find it.

# Actor input Schema

## `apiKey` (type: `string`):

Your own free TMDB key. Create a free account at themoviedb.org, open Settings > API (https://www.themoviedb.org/settings/api), and paste either the 'API Key' or the 'API Read Access Token'. It is stored encrypted.

## `searchType` (type: `string`):

What to get: search movies, TV shows, people or all three; browse with filters (discover); or this week's trending movies, shows and people.

## `query` (type: `string`):

Title or name to search for. Needed for the search types; not used by discover or trending.

## `year` (type: `string`):

Four-digit release year (first air year for TV). Used by movie and TV search and by discover.

## `genre` (type: `string`):

Genre name for discover, such as Action, Comedy, Horror, Documentary, or TV genres such as 'Sci-Fi & Fantasy'.

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

Language of titles and overviews, as a code such as en-US, de-DE, fr-FR or ja-JP.

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

Sort order for discover.

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

Maximum number of results (1-100).

## `includeAdult` (type: `boolean`):

Whether to include adult content in results.

## Actor input object example

```json
{
  "searchType": "multi",
  "query": "Inception",
  "language": "en-US",
  "sortBy": "popularity.desc",
  "maxResults": 20,
  "includeAdult": false
}
```

# Actor output Schema

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

Every result with all fields.

## `overview` (type: `string`):

Movies and shows with poster, dates, rating, votes, popularity and overview.

## `people` (type: `string`):

People results with department and best-known titles.

# 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 = {
    "query": "Inception"
};

// Run the Actor and wait for it to finish
const run = await client.actor("automly/tmdb-movie-tv-api").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 = { "query": "Inception" }

# Run the Actor and wait for it to finish
run = client.actor("automly/tmdb-movie-tv-api").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 '{
  "query": "Inception"
}' |
apify call automly/tmdb-movie-tv-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automly/tmdb-movie-tv-api"
        }
    }
}
```

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/R0MYag6GeBJe8ueIU/builds/bKDgIFrcet5Ia1FOV/openapi.json