Getting started with tmdbR

tmdbR is a modern client for version 3 of The Movie Database (TMDB) API. It retains the read-only interface of the legacy TMDb package while adding bearer authentication, current endpoints, retries, structured errors, and safe automatic pagination.

Authentication

Create an API Read Access Token in your TMDB account. Save it outside scripts:

library(tmdbR)
tmdb_auth(path = file.path(tempdir(), "tmdbR-token.rds"))

For temporary or automated sessions, set an environment variable before loading the package:

Sys.setenv(TMDB_BEARER_TOKEN = "your-token")
library(tmdbR)

Never commit credentials. The older TMDB_API_KEY environment variable remains supported for compatibility, but bearer authentication is recommended.

Search and retrieve details

Search results contain TMDB identifiers that can be passed to detail functions:

hits <- search_movie(query = "Spirited Away", language = "en-AU")
film <- movie(
  id = hits$results$id[[1]],
  append_to_response = "credits,videos"
)

Use help(tmdb_movies), help(tmdb_tv), and help(tmdb_people) to browse functions by subject.

Automatic pagination

Pagination is opt-in. Limits protect users from unexpectedly large requests:

popular <- movie_popular(
  region = "AU",
  paginate = TRUE,
  max_pages = 3,
  max_results = 50,
  progress = TRUE
)

popular$results
popular$pages_fetched
popular$truncated

TMDB controls page size. The package counts actual returned records and follows TMDB’s total_pages value instead of assuming a fixed number of results per page.

Discover filters

Discover endpoints support regional availability and watch-provider filters:

available <- discover_movie(
  watch_region = "AU",
  with_watch_providers = c(8, 9),
  with_watch_monetization_types = "flatrate",
  sort_by = "popularity.desc"
)

Errors and retries

HTTP errors are raised as R errors containing TMDB’s status and message without exposing credentials. Rate-limit responses and transient server failures are retried automatically. Low-level requests can customise this behaviour:

cfg <- tmdb_config(timeout = 30, max_tries = 5)
tmdb_request("movie/550", config = cfg)

Migrating from TMDb 1.1

Most legacy calls remain valid, and the first api_key argument is optional when a bearer token is configured. Important endpoint replacements include:

movie_releases() now uses the current release-dates endpoint.
keyword_movies(), company_movies(), and genres_movies() use supported discover filters.
search_list() maps to collection search because the legacy list-search endpoint is no longer available.

This product uses the TMDB API but is not endorsed or certified by TMDB.