TMDB Scraper: Movie, TV Show, Cast & Episode Data

Scrape TMDB movie data, TV show metadata, actor profiles, cast and crew, seasons, episodes, ratings, genres, posters, trailers, keywords, social links, and recommendations from The Movie Database (TMDB).

This Apify actor is a lightweight TMDB scraper for building entertainment datasets, enriching movie databases, collecting TV episode lists, researching cast and crew, and monitoring titles on TMDB. It supports normal title search, direct TMDB URLs, and optional AI-assisted title discovery.

What This TMDB Scraper Extracts

• Movie details: title, release date, runtime, ratings, genres, certification, budget, revenue, directors, cast, trailers, posters, backdrops, and recommendations
• TV show details: title, first air date, last air date, network, status, type, genres, ratings, number of seasons, number of episodes, posters, backdrops, and trailers
• Actor and person profiles: name, biography, known for, birthday, deathday, place of birth, aliases, profile image, and social links
• Cast and crew data: top cast by default, with optional full cast and crew profile scraping
• TV seasons and episodes: season number, episode count, episode title, air date, runtime, score, still image, and parent show references
• TMDB URLs and IDs for joining records to internal databases

Best Use Cases

• Build a TMDB movie metadata dataset
• Scrape TV shows, seasons, and episodes for catalogs or content apps
• Collect actor, actress, director, cast, and crew profile data
• Enrich entertainment, streaming, media, or recommendation databases
• Monitor selected TMDB movie, TV, person, season, or list pages
• Generate title ideas from prompts such as "dark sci-fi thrillers" and scrape matching TMDB records

Input Options

Use one or more of these input methods:

• searchTerms: Search TMDB by movie title, TV show title, or person name
• startUrls: Scrape known TMDB movie, TV, person, season, search, or list URLs
• enableAiSearch and aiQuery: Convert a natural-language prompt into likely TMDB titles, then scrape those titles

Important controls:

• searchTypes: Choose movie, tv, person, or any combination
• maxResultsPerSearchTerm: Limit how many search results are followed for each search term
• maxItems: Limit the number of dataset records saved by the run
• scrapeFullCast: Visit full cast and crew pages and save linked people as separate records
• scrapeEpisodes: Visit TV season pages and save season and episode records
• strictExactSeriesMatch: Use exact TV-title matching when you want one specific series
• language: Add a TMDB language code to crawled URLs

Quick Start

Search Movies, TV Shows, and People

{
  "searchTerms": ["Inception", "Breaking Bad", "Tom Hanks"],
  "searchTypes": ["movie", "tv", "person"],
  "maxResultsPerSearchTerm": 5,
  "maxItems": 100,
  "language": "en-US"
}

Scrape Direct TMDB URLs

{
  "startUrls": [
    { "url": "https://www.themoviedb.org/movie/27205" },
    { "url": "https://www.themoviedb.org/tv/1399" },
    { "url": "https://www.themoviedb.org/person/31" }
  ],
  "maxItems": 100,
  "language": "en-US"
}

Scrape TV Seasons and Episodes

{
  "searchTerms": ["Friends"],
  "searchTypes": ["tv"],
  "strictExactSeriesMatch": true,
  "scrapeEpisodes": true,
  "maxResultsPerSearchTerm": 1,
  "maxItems": 500,
  "language": "en-US"
}

AI-Assisted TMDB Search

AI mode turns a natural-language prompt into likely TMDB titles before scraping. It requires OPENROUTER_API_KEY and OPENROUTER_MODEL to be configured for the actor.

{
  "enableAiSearch": true,
  "aiQuery": "dark detective thrillers with plot twists",
  "searchTypes": ["movie", "tv"],
  "maxResultsPerSearchTerm": 5,
  "maxItems": 150,
  "language": "en-US"
}

Output

The actor saves structured records to the default dataset. Records can have these entityType values:

• movie
• tv
• person
• season
• episode

Common output fields include:

• tmdbId
• tmdbUrl
• title or name
• description and overview
• release date, first air date, air date, or birthday
• ratings, vote counts, runtime, genres, keywords, and countries
• poster, backdrop, profile image, and still image URLs
• trailer, homepage, Facebook, Instagram, X/Twitter, and JustWatch links
• directors, top cast, networks, parent show references, and recommendations

Example Movie Record

{
  "entityType": "movie",
  "tmdbId": 27205,
  "title": "Inception",
  "releaseDate": "2010-07-15",
  "ratingAverage": 8.4,
  "genres": ["Action", "Science Fiction", "Adventure"],
  "directors": ["Christopher Nolan"],
  "topCast": ["Leonardo DiCaprio", "Joseph Gordon-Levitt", "Elliot Page"],
  "posterUrl": "https://media.themoviedb.org/t/p/original/....jpg",
  "tmdbUrl": "https://www.themoviedb.org/movie/27205?language=en-US"
}

Example TV Show Record

{
  "entityType": "tv",
  "tmdbId": 1399,
  "title": "Game of Thrones",
  "firstAirDate": "2011-04-17",
  "lastAirDate": "2019-05-19",
  "numberOfEpisodes": 73,
  "numberOfSeasons": 8,
  "network": "HBO",
  "tmdbUrl": "https://www.themoviedb.org/tv/1399?language=en-US"
}

Example Person Record

{
  "entityType": "person",
  "tmdbId": 31,
  "name": "Tom Hanks",
  "knownFor": "Acting",
  "birthday": "1956-07-09",
  "placeOfBirth": "Concord, California, USA",
  "tmdbUrl": "https://www.themoviedb.org/person/31?language=en-US"
}

Example Season and Episode Records

{
  "entityType": "season",
  "title": "Season 1",
  "seasonNumber": 1,
  "releaseDate": "1994-09-22",
  "parentShowTitle": "Friends"
}

{
  "entityType": "episode",
  "title": "Pilot",
  "seasonNumber": 1,
  "episodeNumber": 1,
  "airDate": "1994-09-22",
  "parentShowTitle": "Friends"
}

Scaling and Cost Control

This TMDB scraper uses a lightweight HTTP/HTML crawler instead of a browser crawler, which keeps memory usage low and makes it suitable for large datasets.

For large runs:

• Set maxItems to the number of records you want in the dataset
• Leave scrapeFullCast and scrapeEpisodes disabled unless you need those extra linked records
• Use strictExactSeriesMatch=true when scraping full TV episodes from search terms
• The actor uses internal crawler limits to control RAM, request volume, and proxy usage
• The default run timeout is 3600 seconds; use a higher timeout for very large cast or episode crawls

Dataset records are pushed as they are scraped, so the actor does not need to keep thousands of records in memory.

Python API Example

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run_input = {
    "searchTerms": ["Inception", "Breaking Bad"],
    "searchTypes": ["movie", "tv"],
    "maxResultsPerSearchTerm": 5,
    "maxItems": 100,
    "language": "en-US",
}

run = client.actor("thescrapelab/Apify-tmdb-scraper").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

Notes and Limitations

• Best metadata coverage is currently with language: "en-US" because some TMDB fact labels are language-dependent
• AI mode requires both OPENROUTER_API_KEY and OPENROUTER_MODEL to be configured
• AI mode runs first; if it returns no valid titles, the actor falls back to normal searchTerms and startUrls
• strictExactSeriesMatch=true is useful when you only want one exact TV result per search term
• If both scrapeEpisodes=true and scrapeFullCast=true, strict exact TV-series behavior is applied automatically
• This product uses TMDB data but is not endorsed or certified by TMDB