The Movie Database (TMDB) Scraper

The Movie Database (TMDB) Scraper creates a structured dataset of movie, TV show, and person records collected from themoviedb.org. Each dataset item represents one title or person and can include the title, year, overview, genres, user score, vote count, runtime, release date, budget, revenue, poster, and trailer, with optional cast, crew, reviews, awards, alternative titles, and image galleries. Query the source using keyword search, built-in lists, genre and date filters, or direct TMDB URLs, control the result limit with maxItems, and retrieve records through the Apify Dataset API or export them as JSON, CSV, Excel, or XML.

Dataset at a glance

Property	Value
Source	themoviedb.org
Record unit	One movie, TV show, or person
Input methods	searchQueries, lists, startUrls, genre/date/language filters
Main identifiers	tmdbId, url
Delivery	Apify Dataset and API
Export formats	JSON, CSV, Excel, XML
Update model	Fresh records per Actor run
Pricing	$1 per 1,000 events

Coverage and available records

The Actor returns records from TMDB's public website, matching the same list filters as the site. Supported coverage includes:

• Keyword search across movies, TV shows, or people (searchType: all, movie, tv, person).
• Built-in lists for movies (Popular, Now Playing, Upcoming, Top Rated) and TV (Air Today, On The Air, Popular, Top Rated).
• Filtering by genres, release date, air date, first air date, original language, origin country, certification, minimum user score, minimum votes, runtime, keywords, and TV networks.
• Watch-provider filtering by region, provider, and availability (stream, free, ads, rent, buy).
• Direct list, filtered, or title URLs via startUrls.
• Optional full title pages (includeDetails), cast and crew, user reviews, awards, alternative titles, and image galleries.

When lists, searchQueries, and startUrls are all empty, the Actor defaults to Popular Movies and then applies any filters set.

Data dictionary

Field	Type	Nullable	Description	Example
type	string	No	Record type	"movie"
tmdbId	integer	No	TMDB title identifier	1368337
url	string	No	TMDB page URL	"https://www.themoviedb.org/movie/1368337-the-odyssey"
name	string	No	Title or person name	"The Odyssey"
originalTitle	string	Yes	Original-language title	null
tagline	string	Yes	Tagline	"Defy the gods."
overview	string	Yes	Synopsis, when details are enabled	"Odysseus, the legendary King of Ithaca..."
year	integer	Yes	Release or first-air year	2026
releaseDate	string	Yes	Release date (YYYY-MM-DD)	"2026-07-15"
releaseDateText	string	Yes	Localized release date text	"07/16/2026 (DE)"
runtime	string	Yes	Runtime display string	"2h 53m"
runtimeMinutes	integer	Yes	Runtime in minutes	173
userScorePercent	integer	Yes	User score (0–100)	80
userScore	number	Yes	User score (0–10)	8.0
voteCount	integer	Yes	Number of votes	3225
reviewCount	integer	Yes	Number of reviews	28
certification	string	Yes	Age certification	"12"
genres	array	Yes	Genre names	["Adventure", "Action", "Fantasy"]
status	string	Yes	Release status	"Released"
originalLanguage	string	Yes	Original language	"English"
budget	number	Yes	Production budget (USD), when published	250000000.0
revenue	number	Yes	Revenue (USD), when published	1446194550.0
posterUrl	string	Yes	Poster image URL	"https://media.themoviedb.org/t/p/..."
backdropUrl	string	Yes	Backdrop image URL	"https://media.themoviedb.org/t/p/..."
homepageUrl	string	Yes	Official homepage URL	"https://www.facebook.com/OdysseyMovie"
trailerYoutubeId	string	Yes	Trailer YouTube ID	"AyIZ9tiiN8I"
trailerUrl	string	Yes	Trailer URL	"https://www.youtube.com/watch?v=AyIZ9tiiN8I"
keywords	array	Yes	Keyword terms	["greek mythology", "trojan war"]
countriesOfOrigin	array	Yes	Origin countries	["United Kingdom", "United States"]
contentScore	integer	Yes	Popularity/content score	100
cast	array	Yes	Cast members, when enabled	[{"name": "Matt Damon", "tmdbId": 1892, "character": "Odysseus", "url": "..."}]
reviews	array	Yes	User reviews, when enabled	[{"author": "Kingson S", "ratingPercent": 90, "content": "..."}]
awards	array	Yes	Awards, when enabled	[{"name": "Astra Midseason Movie Awards", "tmdbId": "101"}]
alternativeTitles	array	Yes	Alternative titles, when enabled	[{"country": "Italy", "title": "Odissea"}]
featuredCrew	array	Yes	Featured crew, when details are enabled	[{"name": "Christopher Nolan", "job": "Director, Writer"}]

The most stable field for deduplication is tmdbId (falling back to url).

Example dataset record

{
  "type": "movie",
  "tmdbId": 1368337,
  "url": "https://www.themoviedb.org/movie/1368337-the-odyssey",
  "name": "The Odyssey",
  "tagline": "Defy the gods.",
  "overview": "Odysseus, the legendary King of Ithaca, embarks on a long and perilous journey home following the Trojan War...",
  "year": 2026,
  "releaseDate": "2026-07-15",
  "runtime": "2h 53m",
  "runtimeMinutes": 173,
  "userScore": 8.0,
  "voteCount": 3225,
  "reviewCount": 28,
  "certification": "12",
  "genres": ["Adventure", "Action", "Fantasy"],
  "status": "Released",
  "originalLanguage": "English",
  "budget": 250000000.0,
  "revenue": 1446194550.0,
  "posterUrl": "https://media.themoviedb.org/t/p/w300_and_h450_face/5rhTDKUhPYvpdQIijFIs5VoWsON.jpg",
  "trailerUrl": "https://www.youtube.com/watch?v=AyIZ9tiiN8I",
  "keywords": ["greek mythology", "trojan war", "odyssey"],
  "countriesOfOrigin": ["United Kingdom", "United States"],
  "cast": [
    {
      "name": "Matt Damon",
      "tmdbId": 1892,
      "character": "Odysseus",
      "url": "https://www.themoviedb.org/person/1892-matt-damon"
    }
  ],
  "reviews": [
    {
      "author": "Kingson S",
      "ratingPercent": 90,
      "content": "The movie is visually spectacular and good story telling..."
    }
  ],
  "alternativeTitles": [
    {
      "country": "Italy",
      "title": "Odissea"
    }
  ]
}

This record was produced by a movie search for The Odyssey with details, cast and crew, reviews, awards, alternative titles, and images enabled. Cast, reviews, and alternative titles are truncated here.

Query and input reference

Input	Type	Required	Default	Accepted values	Description
searchQueries	array	No	none	Free-text terms	Search TMDB like the site's search box.
searchType	string	No	all	all, movie, tv, person	Which search tab to use.
lists	array	No	none	Popular, Now Playing, Upcoming, Top Rated, Air Today, On The Air	Built-in TMDB lists.
startUrls	array	No	none	TMDB list, filtered, or title URLs	Direct URLs to scrape.
sortBy	string	No	none	popularity.desc, vote_average.desc, title.asc, etc.	Overrides the list default sort.
genres	array	No	none	Genre names or TMDB IDs	Genre filter.
releaseDateFrom / releaseDateTo	string	No	none	YYYY-MM-DD	Release-date bounds.
airDateFrom / airDateTo	string	No	none	YYYY-MM-DD	TV episode air-date bounds.
firstAirDateFrom / firstAirDateTo	string	No	none	YYYY-MM-DD	TV first-air-date bounds.
originalLanguage	string	No	none	ISO 639-1 (e.g. en, ja)	Original language filter.
originCountry	string	No	none	ISO 3166-1 (e.g. US)	Origin country filter.
certifications	array	No	none	Age ratings	Certification filter.
certificationCountry	string	No	none	ISO 3166-1	Certification system to use.
voteAverageMin / voteAverageMax	number	No	none	0–10	User-score bounds.
voteCountMin	integer	No	none	Positive integer	Minimum user votes.
runtimeMin / runtimeMax	integer	No	none	Minutes	Runtime bounds.
keywords	array	No	none	TMDB keyword IDs	Keyword filter.
networks	array	No	none	TMDB network IDs	TV network filter.
watchRegion	string	No	none	ISO 3166-1	Streaming availability region.
watchProviders	array	No	none	Provider names or IDs	Streaming provider filter.
watchMonetizationTypes	array	No	none	stream, free, ads, rent, buy	Availability filter.
releaseTypes	array	No	none	Release type codes	Release-type filter.
includeAdult	boolean	No	false	true / false	Include adult titles.
includeDetails	boolean	No	false	true / false	Open full title pages.
includeCastAndCrew	boolean	No	false	true / false	Include cast and crew.
includeReviews	boolean	No	false	true / false	Include user reviews.
includeAwards	boolean	No	false	true / false	Include awards.
includeAlternativeTitles	boolean	No	false	true / false	Include alternative titles.
includeImages	boolean	No	false	true / false	Include image galleries.
maxItems	integer	No	10	0 (unlimited) or a positive integer	Maximum records to scrape.
proxyConfiguration	object	No	Apify Residential	Apify proxy settings	Proxy configuration.

Minimal request:

{
  "searchQueries": ["The Odyssey"],
  "searchType": "movie",
  "maxItems": 2,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Retrieve the data through the API

1. Start the Actor with a JSON input containing search queries, lists, or start URLs.
2. Wait for the run to finish, or use the synchronous run endpoint.
3. Retrieve items from the run's default dataset via the Dataset API.
4. Paginate the dataset or export it in the required format.

The Apify Console generates ready-to-run code for Python, JavaScript, and other languages in the Actor's API tab; see that tab for the current endpoint and authentication details. Never place a real API token in a URL or example.

Data quality and record handling

• Optional fields (overview, budget, revenue, trailer, cast, reviews, awards, images) are present only when the corresponding detail toggles are enabled.
• User score is normalized into both userScore (0–10) and userScorePercent (0–100).
• Within a run, titles are deduplicated by tmdbId. Across runs, key on tmdbId.
• If a title page fails, the Actor skips that item and continues; check run logs for warnings.
• Enable Apify Residential proxies (the default) to reduce blocks; lower maxItems while testing.

Export and pipeline examples

Destination	Recommended method	Typical use
PostgreSQL/Supabase	Dataset API or webhook consumer	Store title records keyed on tmdbId
Google Sheets	Apify integration	Shareable title catalog
S3/cloud storage	Scheduled export or integration	Periodic catalog archive

Pricing and cost examples

Billing is pay-per-event. Each record written to the dataset is one dataset-item charge; enabling details, cast and crew, reviews, awards, alternative titles, or images adds a corresponding per-record charge at the same rate. Reviews are charged per review. apify-actor-start is a small one-time per-run charge.

Records	Estimated base cost
1,000 titles	$1.00
10,000 titles	$10.00

Estimates assume the published pay-per-event model and do not include Apify platform usage; Apify subscription plan discounts may reduce the per-event rate. Enabling the optional enrichments increases cost per title.

Limitations and responsible data use

• Only publicly accessible themoviedb.org data is returned; no TMDB API key is required.
• Extraction depends on TMDB's current availability and site structure, which can change without notice.
• Conditional fields may be missing for individual titles.
• No historical snapshots are stored unless the user archives dataset exports.
• Users are responsible for compliance with applicable terms of service and privacy obligations.

Dataset questions

What does one dataset item represent?

One dataset item is a single movie, TV show, or person record, identified by tmdbId.

Which field should I use as a unique identifier?

Use tmdbId; it is unique per title and stable across runs.

Are fields nullable or conditional?

Yes. overview, budget, revenue, tagline, trailerUrl, and detail sections such as cast, reviews, and awards are conditional on the title and on the enabled toggles.

Can I retrieve the records as CSV or JSON?

Yes. The dataset can be exported as JSON, CSV, Excel, or XML from the Apify Console or Dataset API.

How do I paginate large datasets?

Raise maxItems (set 0 for unlimited) to collect more records in a single run, then paginate via the Dataset API.

What counts as a billable result?

Each title record written to the dataset is one dataset-item charge; optional details, cast and crew, reviews, awards, alternative titles, and images add one charge each at the same rate.

Related datasets from Data Scrapers

• YouTube Channel Scraper — channel records for cross-platform media research.
• YouTube Comment Scraper — audience comment records for engagement analysis.
• Reddit Community Scraper — community post records for content and audience research.
• TripAdvisor Reviews Scraper — structured review records for sentiment and ratings analysis.

Data Scrapers support

Need an additional field, record type, or export workflow? Contact Data Scrapers at stardustspotlight@gmail.com. Include a sample source URL, required fields, expected record volume, and preferred delivery format.