TMDB (The Movie Database)

Implementation notes

When to use TMDB (The Movie Database)

TMDB is the default choice for movie and TV metadata when you are not paying for a commercial catalog. A free key covers unlimited non-commercial use across a genuinely deep dataset — hundreds of thousands of titles, full cast and crew, translated titles and overviews in 40+ languages, watch-provider availability by country, and artwork at multiple resolutions. The tradeoff is a hard attribution requirement: you must display the TMDB logo and the statement that your product uses TMDB but is not endorsed or certified by TMDB. That is a real product constraint, not a footnote — decide where the logo lives before you design the UI. Choose TMDB over OMDb when you need images, multi-language data, or proper TV season and episode structure; choose OMDb when all you want is an IMDb-keyed ratings lookup. Commercial products need a separate agreement, which TMDB grants readily but you have to ask for it rather than assume it.

Common pitfalls

• Image fields return relative paths like /kqjL17yufvn9OVLyXYpvtyrFfak.jpg, not URLs. You must call /3/configuration once, read images.secure_base_url, pick a size from poster_sizes or backdrop_sizes, and concatenate base + size + path. Cache that configuration response for about a day, and never hardcode the CDN hostname — TMDB has rotated it before, and every hardcoded integration lost all its images the same afternoon.
• There are two credential systems and they are not interchangeable. The v3 API key goes in an api_key query parameter; the v4 read access token is a JWT that goes in an Authorization Bearer header. Sending a v3 key as a Bearer token returns 401 with a message about an invalid token, which sends people hunting for a key-activation problem that does not exist.
• TMDB removed its documented 40-requests-per-10-seconds limit in 2024, but abuse protection is still live and unpublished. Sustained bursts from one IP get throttled or temporarily blocked, and there is no Retry-After you can rely on. Treat roughly 20 requests per second as the practical ceiling and add jitter to any bulk backfill.
• Detail endpoints support append_to_response, which folds sub-resources into a single call: /3/movie/550?append_to_response=credits,videos,images,recommendations turns five round-trips into one. Building a movie detail page without it is the single most common cause of slow TMDB integrations, and it costs one request instead of five against the burst protection above.

Quick start (bash)

# 1. fetch the image base URL once and cache it for ~24h
curl -s 'https://api.themoviedb.org/3/configuration?api_key=YOUR_KEY' | jq -r '.images.secure_base_url'
# 2. movie + credits + videos in a single round-trip
curl -s 'https://api.themoviedb.org/3/movie/550?api_key=YOUR_KEY&append_to_response=credits,videos' | jq '.title, .poster_path'
# poster_path is relative: secure_base_url + w500 + poster_path

Embed this badge

Add a live status badge to your README, docs, or website.

Markdown

[![TMDB (The Movie Database) Status](https://api.freeapi.watch/badge/tmdb.svg)](https://freeapi.watch/tmdb)

HTML

<a href="https://freeapi.watch/tmdb"><img src="https://api.freeapi.watch/badge/tmdb.svg" alt="TMDB (The Movie Database) Status"/></a>