TMDB Scraper (Apify)

Scrapes The Movie Database (TMDB) and outputs structured records for:

• Movies
• TV shows
• People
• Seasons (optional)
• Episodes (optional)

What This Actor Can Do

• Crawl by searchTerms (discovery mode)
• Crawl by startUrls (direct URL mode)
• Filter search results by type: movie, tv, person
• Optionally crawl full cast pages (scrapeFullCast)
• Optionally crawl season and episode pages (scrapeEpisodes)
• AI Recommendation Search: convert a vibe query into 10-20 TMDB titles, then run normal scraping on those titles

Quick Start

1. Standard search mode

Use searchTerms when you want TMDB discovery search.

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

2. Direct URL mode

Use startUrls when you already know TMDB pages to scrape.

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

3. AI Recommendation Search mode

Set enableAiSearch=true and provide aiQuery.

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

Gemini API Key

You have 2 options:

1. Put the key into input as geminiApiKey.
2. Set Actor environment variable GEMINI_API_KEY.

If GEMINI_API_KEY is set, geminiApiKey can be left empty.

AI Billing Event

When AI mode succeeds and generated titles are enqueued, the actor calls:

await Actor.charge({ eventName: 'ai-recommendation' });

This is wrapped in try/catch so local development does not crash when charging is unavailable.

Output Schema

This Actor includes Apify output/schema files:

• .actor/actor.json links input, output, and dataset schema definitions
• .actor/output_schema.json defines output links shown in the Run Output tab
• .actor/dataset_schema.json defines dataset item fields and an overview view

Sample Output Records

Movie record

{
  "entityType": "movie",
  "tmdbId": 27205,
  "tmdbUrl": "https://www.themoviedb.org/movie/27205?language=en-US",
  "sourceSearchTerm": "Inception",
  "title": "Inception",
  "description": "A thief who steals corporate secrets through dream-sharing technology...",
  "originalTitle": "Inception",
  "releaseDate": "2010-07-15",
  "releaseYear": 2010,
  "duration": 148,
  "userScore": 84,
  "ratingAverage": 8.4,
  "ratingCount": 38000,
  "genres": ["Action", "Science Fiction", "Adventure"],
  "tagline": "Your mind is the scene of the crime.",
  "overview": "A thief who steals corporate secrets through dream-sharing technology...",
  "directors": ["Christopher Nolan"],
  "topCast": ["Leonardo DiCaprio", "Joseph Gordon-Levitt", "Elliot Page"],
  "status": "Released",
  "originalLanguage": "English",
  "budget": 160000000,
  "revenue": 825532764,
  "certification": "PG-13",
  "keywords": ["dream", "subconscious", "heist"],
  "countries": ["United States of America", "United Kingdom"],
  "trailerUrl": "https://www.youtube.com/watch?v=YoHD9XEInc0",
  "posterUrl": "https://image.tmdb.org/t/p/original/....jpg",
  "backdropUrl": "https://image.tmdb.org/t/p/original/....jpg",
  "recommendations": [
    { "title": "Interstellar", "url": "https://www.themoviedb.org/movie/157336" }
  ]
}

TV record

{
  "entityType": "tv",
  "tmdbId": 1399,
  "tmdbUrl": "https://www.themoviedb.org/tv/1399?language=en-US",
  "sourceSearchTerm": "Game of Thrones",
  "title": "Game of Thrones",
  "description": "Seven noble families fight for control of the lands of Westeros...",
  "originalTitle": "Game of Thrones",
  "firstAirDate": "2011-04-17",
  "firstAirYear": 2011,
  "lastAirDate": "2019-05-19",
  "userScore": 84,
  "ratingAverage": 8.4,
  "ratingCount": 24000,
  "genres": ["Sci-Fi & Fantasy", "Drama", "Action & Adventure"],
  "overview": "Seven noble families fight for control of the lands of Westeros...",
  "status": "Ended",
  "type": "Scripted",
  "network": "HBO",
  "networks": [
    { "id": 49, "name": "HBO", "url": "https://www.themoviedb.org/network/49" }
  ],
  "originalLanguage": "English",
  "numberOfEpisodes": 73,
  "numberOfSeasons": 8,
  "keywords": ["kingdom", "dragon", "throne"],
  "trailerUrl": "https://www.youtube.com/watch?v=KPLWWIOCOOQ",
  "posterUrl": "https://image.tmdb.org/t/p/original/....jpg",
  "backdropUrl": "https://image.tmdb.org/t/p/original/....jpg"
}

Episode record

{
  "entityType": "episode",
  "tmdbId": 63056,
  "episodeId": "63056",
  "tmdbUrl": "https://www.themoviedb.org/tv/1668-friends/season/1/episode/1?language=en-US",
  "sourceSearchTerm": "Friends",
  "title": "The One Where Monica Gets a Roommate",
  "description": "Rachel runs from her wedding and meets Monica...",
  "episodeNumber": 1,
  "seasonNumber": 1,
  "airDate": "1994-09-22",
  "runtime": 22,
  "userScore": 78,
  "overview": "Rachel runs from her wedding and meets Monica...",
  "stillUrl": "https://image.tmdb.org/t/p/original/....jpg",
  "parentShowUrl": "https://www.themoviedb.org/tv/1668-friends?language=en-US",
  "parentShowTitle": "Friends",
  "parentShowTmdbId": 1668,
  "parentUrl": "https://www.themoviedb.org/tv/1668-friends?language=en-US",
  "parentTitle": "Friends",
  "parentTmdbId": 1668,
  "parentEntityType": "tv"
}

Person record

{
  "entityType": "person",
  "tmdbId": 31,
  "tmdbUrl": "https://www.themoviedb.org/person/31?language=en-US",
  "sourceSearchTerm": "Tom Hanks",
  "name": "Tom Hanks",
  "biography": "Thomas Jeffrey Hanks is an American actor and filmmaker...",
  "knownFor": "Acting",
  "knownCredits": 120,
  "gender": "Male",
  "birthday": "1956-07-09",
  "deathday": "",
  "placeOfBirth": "Concord, California, USA",
  "alsoKnownAs": ["Thomas J. Hanks", "Tom Hanks"],
  "profileUrl": "https://image.tmdb.org/t/p/original/....jpg",
  "facebookUrl": null,
  "twitterUrl": null,
  "instagramUrl": null,
  "homepageUrl": null,
  "justWatchUrl": null,
  "parentUrl": null,
  "parentTitle": null,
  "parentTmdbId": null,
  "parentEntityType": null
}

Season record

{
  "entityType": "season",
  "tmdbId": null,
  "tmdbUrl": "https://www.themoviedb.org/tv/1668-friends/season/1?language=en-US",
  "sourceSearchTerm": "Friends",
  "title": "Season 1",
  "seasonNumber": 1,
  "releaseDate": "1994-09-22",
  "episodeCount": 24,
  "posterUrl": "https://image.tmdb.org/t/p/original/....jpg",
  "parentShowUrl": "https://www.themoviedb.org/tv/1668-friends?language=en-US",
  "parentShowTitle": "Friends",
  "parentShowTmdbId": 1668,
  "parentUrl": "https://www.themoviedb.org/tv/1668-friends?language=en-US",
  "parentTitle": "Friends",
  "parentTmdbId": 1668,
  "parentEntityType": "tv"
}

Notes

• AI mode runs first. If AI returns no valid titles, the actor falls back to normal searchTerms/startUrls flow.
• strictExactSeriesMatch=true forces one exact TV title match per search term.
• If both scrapeEpisodes=true and scrapeFullCast=true, strict exact series behavior is also applied automatically.