Skip to content
@deckyard/tmdb

@deckyard/tmdb

A typed Jennifer client for The Movie Database.

This deck is part of Deckyard, community decks for Jennifer.

jennifer
use io;
import "@deckyard/tmdb/" as tmdb;

def c as tmdb.Client init tmdb.clientFromEnv();
def hits as tmdb.MoviePage init tmdb.searchMovies($c, "blade runner", 1);

for (def m in $hits.results) {
    io.printf("%s (%s)  %.1f\n", $m.title, tmdb.year($m.releaseDate), $m.voteAverage);
}

v3 and v4

TMDB serves two API generations from one host, https://api.themoviedb.org. v4 (/4/...) has bearer authentication, the user approval flow, accounts and custom lists, but cannot search or describe a film. v3 (/3/...) has the catalogue: films, series, seasons, episodes, people, credits, images, videos, genres, discovery and watch providers.

The v4 API Read Access Token is a bearer credential both generations accept, so one Client with one token reaches /3/movie/550 and /4/list/8175284 alike.

What the deck does on top of the HTTP API:

  • Replies are value-semantic structs. A null or missing field reads as "", 0, false or [], so a struct is always safe to read.
  • Films and series share field names: title is filled from title or name, releaseDate from release_date or first_air_date, and the discovery filter writes primary_release_date.gte or first_air_date.gte as the catalogue needs.
  • Arguments are checked before the request: a zero id, a page outside 1..500, an image size that does not exist for that kind, a path carrying ...
  • Every failure is Error{kind: "tmdb"}, carrying TMDB's own status_message when there is one.
  • tmdb.call, tmdb.callPost, tmdb.callPut and tmdb.callDelete reach any endpoint without a typed verb.

Coverage

topicendpoints
Searchmovie, tv, person, multi, collection, company, keyword
Discovery/discover/movie, /discover/tv, behind a filter builder
Moviesdetails, credits, images, videos, keywords, recommendations, similar, reviews, release dates, external ids, translations, alternative titles, watch providers, now playing, popular, top rated, upcoming, latest
Seriesdetails, credits, aggregate credits, images, videos, keywords, content ratings, episode groups, recommendations, similar, reviews, external ids, translations, alternative titles, watch providers, airing today, on the air, popular, top rated, latest
Seasons and episodesdetails, credits, aggregate credits, images, videos, external ids
Peopledetails, movie / tv / combined credits, images, external ids, popular, latest
Cataloguecollections, companies, networks, keywords, reviews, credits, find
Browsingtrending, genres, certifications, watch providers, change feeds
Configurationimages, countries, languages, primary translations, jobs, time zones
v4 authrequest token, approval URL, access token, logout
v4 accountlists, favourites, ratings, watchlists, recommendations
v4 listscreate, read, update, delete, clear, add and remove items, item status

Errors lists what can fail and the messages, Recipes has complete programs, and the cheatsheet lists every export.

Attribution

This product uses the TMDB API but is not endorsed or certified by TMDB. Using the API means agreeing to its terms of use, which require you to attribute TMDB in any application built on it. The watch-provider data is JustWatch's and carries its own attribution requirement.