TMDB APItmdb.org ↗
Access TMDB data via 10 endpoints: search movies/TV/people, get cast, crew, reviews, images, videos, trending titles, and watch providers.
What is the TMDB API?
This API exposes 10 endpoints covering The Movie Database (TMDB), returning structured data for movies, TV shows, and people. The get_movie_details endpoint alone surfaces over a dozen fields including budget, revenue, genres, keywords, tagline, user score, and schema.org metadata. Other endpoints cover cast and crew, images, videos, user reviews, trending titles, popular movies, TV show details, and per-title watch provider availability grouped by stream, rent, and buy.
curl -X GET 'https://api.parse.bot/scraper/fa1f32a6-9d98-438e-961b-9087d0d99df1/search?query=inception' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tmdb-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TMDB SDK — search, browse trending, drill into movie details."""
from parse_apis.tmdb_scraper_api import TMDB, TimeWindow, MediaType, ContentNotFound
client = TMDB()
# Search for movies/TV by keyword; limit= caps total items fetched.
for result in client.movies.search(query="inception", limit=3):
print(result.name, result.media_type, result.vote_average)
# Browse trending content for this week.
for item in client.trendingitems.list(time_window=TimeWindow.DAY, limit=5):
print(item.title, item.type, item.id_slug)
# Drill into a specific movie via constructible MovieSummary.
movie_summary = client.moviesummary(id_slug="550-fight-club")
movie = movie_summary.details()
print(movie.title, movie.genres, movie.user_score)
# Walk sub-resources: videos and reviews for the movie.
for video in movie.videos.list(limit=3):
print(video.title, video.type, video.url)
# Typed error handling: catch ContentNotFound for an invalid slug.
try:
bad = client.tvshows.get(tv_id_slug="99999999-nonexistent")
print(bad.title)
except ContentNotFound as exc:
print(f"TV show not found: {exc}")
# Get watch providers for a movie.
providers = client.watchproviderses.get(id_slug="550-fight-club", media_type=MediaType.MOVIE)
if providers.Rent:
print(f"Rent from: {providers.Rent[0].name}")
print("exercised: movies.search / trendingitems.list / moviesummary.details / videos.list / tvshows.get / watchproviderses.get")
Full-text search across movies, TV shows, and people on TMDB. Returns mixed-type results ordered by relevance; each result carries a media_type discriminator.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword (e.g. 'inception', 'breaking bad') |
{
"type": "object",
"fields": {
"items": "array of search result objects with id, name, media_type, overview, poster_url, and other metadata"
},
"sample": {
"data": {
"items": [
{
"id": 27205,
"name": "Inception",
"overview": "Cobb, a skilled thief...",
"media_type": "movie",
"popularity": 33.3385,
"poster_url": "https://image.tmdb.org/t/p/w500/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
"vote_average": 8.372
}
]
},
"status": "success"
}
}About the TMDB API
Search and Discovery
The search endpoint accepts a query string and returns an array of results across movies, TV shows, and people, each with an id, name, media_type, overview, and poster_url. The media_type field lets you branch downstream calls — use the returned id_slug with get_movie_details or get_tv_show_details accordingly. For browsing without a query, get_popular_movies accepts an optional page parameter and returns paginated results with title, release date, poster, score, and id_slug. get_trending accepts a time_window of 'day' or 'week' and returns trending movies and TV shows with their type flag.
Movie Detail Endpoints
get_movie_details takes a movie_id_slug (e.g. '27205-inception') and returns a full metadata object: title with year, plot overview, formatted budget and revenue, tagline, release status, genre array, keyword array, user score out of 100, and a metadata object containing schema.org JSON-LD. get_movie_cast_crew returns a cast array — each member has name, id_slug, role, and profile_url — and a crew object keyed by department name. get_movie_images returns separate posters and backdrops arrays, each entry carrying a URL and descriptive info string. get_movie_videos returns video entries with title, type (trailer, teaser, etc.), and a YouTube or Vimeo URL. get_movie_reviews returns author name, review content, and rating (nullable) for each user review.
TV Shows and Watch Providers
get_tv_show_details accepts a tv_id_slug (e.g. '1396-breaking-bad') and returns the show title with year, overview, first air year, an array of network objects with name and logo, and schema.org metadata. get_watch_providers accepts an id_slug and a media_type of 'movie' or 'tv', and returns provider arrays grouped under Stream, Rent, and Buy — each provider includes a name and logo. Watch provider availability reflects the data TMDB has for the given title.
The TMDB API is a managed, monitored endpoint for tmdb.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tmdb.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tmdb.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a movie search interface that displays poster, overview, and user score from the
searchandget_movie_detailsendpoints. - Populate a 'Where to Watch' feature using
get_watch_providersto show streaming, rental, and purchase options per title. - Create a trending content feed for a homepage using
get_trendingwith a daily or weekly time window. - Generate cast pages by combining
get_movie_cast_crewactorid_slugvalues with profile URLs. - Display trailer and teaser embeds on a movie detail page using video URLs from
get_movie_videos. - Aggregate user sentiment by pulling review content and ratings via
get_movie_reviewsfor analysis or display. - Support editorial content by pulling budget, revenue, genres, and keywords from
get_movie_detailsfor box-office comparison features.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does The Movie Database have an official developer API?+
What does `get_movie_cast_crew` return and how is the crew data structured?+
cast array where each entry includes the actor's name, id_slug, role (character name), and profile_url. The crew field is an object keyed by department name (e.g. Directing, Writing, Production), with each value being an array of crew member objects.Does the API cover individual TV season or episode details?+
get_tv_show_details, including overview, networks, and first air year, but does not expose per-season or per-episode fields. You can fork this API on Parse and revise it to add an endpoint targeting season or episode detail pages.Are watch provider results global or region-specific?+
get_watch_providers endpoint returns provider data as it appears on the TMDB page for the given title. TMDB's own provider data is region-dependent — the results reflect availability shown for the default region on the page, not a user-selectable country filter. If you need region-specific provider data, you can fork this API on Parse and revise the endpoint to target a locale-specific URL.Does the API return person (actor/director) biography pages?+
search endpoint identifies people with a media_type of person and returns basic metadata, and cast entries in get_movie_cast_crew include a profile_url, but there is no dedicated person detail endpoint exposing biography, birthdate, or filmography. You can fork this API on Parse and revise it to add a person detail endpoint.