Movie Lists

The movieLists module provides access to curated and time-sensitive lists of movies from TMDB. These lists include "now playing", "popular", "top rated", and "upcoming" movies.

Now Playing

tmdb.movieLists.now_playing Get a list of movies currently playing in theaters.

tmdb.movieLists.now_playing(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>

TMDB Reference:

https://developer.themoviedb.org/reference/movie-now-playing-list

tmdb.movieLists.popular

Get a list of movies ordered by popularity.

tmdb.movieLists.popular(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>

TMDB Reference:

https://developer.themoviedb.org/reference/movie-popular-list

Top Rated

tmdb.movieLists.top_rated

Get a list of movies ordered by rating.

tmdb.movieLists.top_rated(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>

TMDB Reference:

https://developer.themoviedb.org/reference/movie-top-rated-list

Upcoming

tmdb.movieLists.upcoming

Get a list of upcoming movies.

tmdb.movieLists.upcoming(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>

TMDB Reference:

https://developer.themoviedb.org/reference/movie-upcoming-list

Usage Example

const upcoming = await tmdb.movieLists.upcoming();
console.log(upcoming.results.map(movie => movie.title));

Parameters

All the movie list methods make use of the same parameters:

NameTypeRequiredDescription
languagestring❌Language of the results (default: en-US)
pagenumber❌Page number for pagination (default: 1)
regionstring❌ISO 3166-1 country code for region-specific results

Types

The following TypeScript types are used in the methods above:

type MovieResultItem = {
  id: number;
  title: string;
  original_title: string;
  release_date: string;
  overview: string;
  poster_path: string | null;
  backdrop_path: string | null;
  vote_average: number;
  vote_count: number;
  popularity: number;
  genre_ids: number[];
  original_language: string;
  adult: boolean;
  video: boolean;
};

type PaginatedResponse<T> = {
  page: number;
  total_pages: number;
  total_results: number;
  results: T[];
};

These types are imported from the SDK and ensure fully typed responses for all movie list endpoints. You can import single types using

import type { MovieResultItem } from '@lorenzopant/tmdb'