API Reference

@lorenzopant/tmdb exposes the full TMDB API surface through a set of focused, typed client classes. You can use them in two ways: through the unified TMDB client, or as standalone classes when you only need a specific subset of functionality.

Using the unified client

The TMDB class bundles all APIs under a single instance. This is the recommended approach for most use cases.

import { TMDB } from "@lorenzopant/tmdb";

const tmdb = new TMDB("your-api-key", {
	language: "en-US",
	region: "US",
});

// Access any API namespace directly
const popular = await tmdb.movies.popular();
const trending = await tmdb.tv_series.trending("day");
const results = await tmdb.search.movie({ query: "Inception" });

Using standalone API classes

Each API is also available as a standalone class — useful when you want to tree-shake or only import what you need.

import { MoviesAPI } from "@lorenzopant/tmdb";

const moviesApi = new MoviesAPI("your-api-key", {
	language: "it-IT",
	region: "IT",
});

const popular = await moviesApi.popular();
const details = await moviesApi.details(550);

import { SearchAPI } from "@lorenzopant/tmdb";

const searchApi = new SearchAPI("your-api-key");
const results = await searchApi.movie({ query: "The Godfather" });

import { TVSeriesAPI } from "@lorenzopant/tmdb";

const tvApi = new TVSeriesAPI("your-api-key", {
	language: "ja-JP",
	timezone: "Asia/Tokyo",
});

const airingToday = await tvApi.airingToday();

Available APIs

API	Unified client accessor	Standalone class	Description
Authentication	`tmdb.authentication`	`AuthenticationAPI`	Manage v3 user sessions — create request tokens, exchange them for session IDs, and log users out.
Account	`tmdb.account`	`AccountAPI`	Manage account favorites, watchlists, ratings, and custom lists.
Discover	`tmdb.discover`	`DiscoverAPI`	Discover movies and TV series with advanced TMDB filters, sorting, and pagination.
Find	`tmdb.find`	`FindAPI`	Find movies, TV shows, seasons, episodes, and people by external IDs.
Watch Providers	`tmdb.watch_providers`	`WatchProvidersAPI`	Retrieve movie/TV provider catalogs and supported watch-provider regions.
Keywords	`tmdb.keywords`	`KeywordsAPI`	Retrieve keyword details and the associated movie list by TMDB keyword ID.
Companies	`tmdb.companies`	`CompaniesAPI`	Get company details, alternative names, and logos for production companies.
Credits	`tmdb.credits`	`CreditsAPI`	Get credit details for a movie or tv show.
Networks	`tmdb.networks`	`NetworksAPI`	Get TV network details, alternative names, and logos by TMDB network ID.
Configuration	`tmdb.configuration`	`ConfigurationAPI`	Retrieve system-level configuration such as image base URLs and languages.
Genres	`tmdb.genres`	`GenresAPI`	Fetch the list of official movie and TV series genres.
Movie Lists	`tmdb.movieLists`	`MovieListsAPI`	Access curated movie lists: popular, top rated, now playing, and upcoming.
Movies	`tmdb.movies`	`MoviesAPI`	Get movie details, credits, images, videos, recommendations, and more.
People	`tmdb.people`	`PeopleAPI`	Get person details, credits, images, translations, and external IDs.
People Lists	`tmdb.people_lists`	`PeopleListsAPI`	Get curated lists of people ordered by popularity.
Search	`tmdb.search`	`SearchAPI`	Search for movies, TV series, people, and keywords across the TMDB catalog.
Trending	`tmdb.trending`	`TrendingAPI`	Get trending movies, TV series, and people on TMDB.
Reviews	`tmdb.reviews`	`ReviewsAPI`	Get the full details of a single TMDB review by its review ID.
TV Series	`tmdb.tv_series`	`TVSeriesAPI`	Get TV series details, episodes, seasons, credits, and recommendations.
TV Episode Groups	`tmdb.tv_episode_groups`	`TVEpisodeGroupsAPI`	Get episode group details by group ID.
TV Episodes	`tmdb.tv_episodes`	`TVEpisodesAPI`	Get TV episode details, credits, images, translations, and videos.
TV Seasons	`tmdb.tv_seasons`	`TVSeasonsAPI`	Get TV season details, credits, images, videos, translations, and watch providers.
TV Series Lists	`tmdb.tv_series_lists`	`TVSeriesListsAPI`	Access curated TV series lists: popular, top rated, airing today, and on the air.

API V4

The TMDB v4 API is available under the tmdb.v4 namespace. It provides methods for user authentication and account management.

API	Unified client accessor	Standalone class	Description
Auth	`tmdb.v4.auth`	`V4AuthAPI`	TMDB v4 OAuth-style authentication — create request tokens, exchange them for access tokens, and log users out.

Constructor signature

All standalone API classes share the same constructor signature:

new SomeAPI(apiKey: string, options?: TMDBOptions)

Parameter	Type	Description
`apiKey`	`string`	Your TMDB API key.
`options`	`TMDBOptions`	Optional default values for language, region, timezone and images.

See the Options reference for the full list of available configuration options.