TMDB

📌 Overview

A lightweight and pragmatic TypeScript client for the TMDB API, focused on simplicity, direct API mapping, and developer control.

Unlike more abstraction-heavy libraries, this client provides predictable structures and explicit endpoint access, making it suitable for backend services and controlled environments.

📌 Maintenance

This package is still maintained, but development is driven by practical needs and may not include all TMDB API features.

Some missing endpoints are intentionally not implemented or replaced with alternative abstractions.

🚀 Key Characteristics

• Simple and predictable API design
• Optional default language configuration
• Minimal abstraction over TMDB endpoints
• Suitable for backend services and controlled environments
• Lightweight with no unnecessary dependencies

⚠️ Notes on Types

Type definitions are based on TMDB responses, which are not always consistent or fully accurate.

Some types may be duplicated or simplified to ensure usability within TypeScript.

Install

npm i @blacktiger/tmdb

Usage

The API key is validated during instance initialization.

import TMDB from '@blacktiger/tmdb';

const tmdb = new TMDB(/* Your API Key */, /* Optional Language, Default: en-US */);

📚 Supported Endpoints

The following sections list supported TMDB API endpoints grouped by category.

Account

Feature	Status
Details	✅
Add Favorite	✅
Add To Watchlist	✅
Favorite Movies	✅
Favorite TV	✅
Lists	✅
Rated Movies	✅
Rated TV	✅
Rated TV Episodes	✅
Watchlist Movies	✅
Watchlist TV	✅

Authentication

Feature	Status
Create Guest Session	✅
Create Request Token	✅
Create Session	✅
Create Session (from v4 token)	✅
Create Session (with login)	✅
Delete Session	✅
Validate Key	✅

Certifications

Feature	Status
Movie Certifications	✅
TV Certifications	✅

Changes

Feature	Status
Movie List	✅
People List	✅
TV List	✅

Collections

Feature	Status
Details	✅
Images	✅
Translations	✅

Companies

Feature	Status
Details	✅
Alternative Names	✅
Images	✅

Configuration

Feature	Status
Details	✅
Countries	✅
Jobs	✅
Languages	✅
Primary Translations	✅
Timezones	✅

Credits

Feature	Status
Details	✅

Discover

Feature	Status
Movie	✅
TV	✅

Find

Feature	Status
Find By ID	✅

Genres

Feature	Status
Movie List	✅
TV List	✅

Guest Sessions

Feature	Status
Rated Movies	✅
Rated TV	✅
Rated TV Episodes	✅

Keywords

Feature	Status
Details	✅
Movies	☑️ Outdated

Lists

v3 or v4 lists?

Feature	Status
Add Movie	✅
Check Item Status	✅
Clear	✅
Create	✅
Delete	✅
Details	✅
Remove Movie	✅

Movie Lists

Feature	Status
Now Playing	✅
Popular	✅
Top Rated	✅
Upcoming	✅

Movies

Feature	Status
Details	✅
Account States	✅
Alternative Titles	✅
Changes	✅
Credits	✅
External IDs	✅
Images	✅
Keywords	✅
Latest	✅
Lists	✅
Recommendations	✅
Release Dates	✅
Reviews	✅
Similar	✅
Translations	✅
Videos	✅
Watch Providers	✅
Add Rating	✅
Delete Rating	✅

Network

Feature	Status
Details	✅
Alternative Names	✅
Images	✅

People Lists

Feature	Status
Popular	✅

People

Feature	Status
Details	✅
Changes	✅
Combined Credits	✅
External IDs	✅
Images	✅
Latest	✅
Movie Credits	✅
TV Credits	✅
Tagged Images	☑️ Outdated
Translations	✅

Reviews

Feature	Status
Details	✅

Search

Feature	Status
Collection	✅
Company	✅
Keyword	✅
Movie	✅
Multi	✅
Person	✅
TV	✅

Trending

Feature	Status
All	❌
Movies	❌
People	❌
TV	❌

TV Series Lists

Feature	Status
Airing Today	❌
On The Air	❌
Popular	❌
Top Rated	❌

TV Series

Feature	Status
Details	✅
Account States	✅
Aggregate Credits	✅
Alternative Titles	✅
Changes	✅
Content Ratings	✅
Credits	✅
Episode Groups	✅
External IDs	✅
Images	✅
Keywords	✅
Latest	✅
Lists	✅
Recommendations	✅
Reviews	✅
Screened Theatrically	✅
Similar	✅
Translations	✅
Videos	✅
Watch Providers	✅
Add Rating	✅
Delete Rating	✅

TV Seasons

Feature	Status
Details	❌
Account States	❌
Aggregate Credits	❌
Changes	❌
Credits	❌
External IDs	❌
Images	❌
Translations	❌
Videos	❌
Watch Providers	❌

TV Episodes

Feature	Status
Details	❌
Account States	❌
Changes	❌
Credits	❌
External IDs	❌
Images	❌
Translations	❌
Videos	❌
Add Rating	❌
Delete Rating	❌

TV Episode Groups

Feature	Status
Details	✅

Watch Providers

Feature	Status
Available Regions	✅
Movie Providers	✅
TV Providers	✅

🤔 When to Use

Use this client if you:

• Prefer a simple and explicit TMDB API wrapper
• Want control over requests and responses
• Need a lightweight solution without heavy abstractions

🚫 When Not to Use

Consider alternatives if you:

• Require full TMDB API coverage
• Need advanced query composition (e.g. append_to_response patterns)
• Prefer highly abstracted or auto-generated clients