Movie Lists

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

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

Now Playing

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

tmdb.movie_lists.now_playing(params: MovieListParams): Promise<PaginatedResponse<MovieResultItem>>

Reference

TMDB - Now Playing Movies

tmdb.movie_lists.popular

Get a list of movies ordered by popularity.

tmdb.movie_lists.popular(params: MovieListParams): Promise<PaginatedResponse<MovieResultItem>>

Reference

TMDB - Popular Movies

Top Rated

tmdb.movie_lists.top_rated

Get a list of movies ordered by rating.

tmdb.movie_lists.top_rated(params: MovieListParams): Promise<PaginatedResponse<MovieResultItem>>

Reference

TMDB - Top Rated Movies

Upcoming

tmdb.movie_lists.upcoming

Get a list of upcoming movies.

tmdb.movie_lists.upcoming(params: MovieListParams): Promise<PaginatedResponse<MovieResultItem>>

Reference

TMDB - Upcoming Movies

Usage Example

const upcoming = await tmdb.movie_lists.upcoming({ region: "CA" });
console.log(upcoming.results.map((movie) => movie.title));

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[];
};

type MovieListParams = {
    language?: LanguageISO6391;
    page?: number;
    region?: CountryISO3166_1;
};

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";