A powerful and easy-to-use TypeScript wrapper for The Movie Database (TMDb) API
The TMDB Api Wrapper simplifies the process of making API requests to The Movie Database (TMDb), a comprehensive database for movies and TV shows. It encapsulates functionality related to various API endpoints, such as account, certifications, changes, collections, configuration, credits, discover, find, genres, keywords, movies, people, reviews, search, trending, TV episodes, TV seasons, TV shows, companies, networks, and watch providers. With this wrapper, developers can quickly integrate TMDB functionality into their TypeScript projects.
- Installation
- Usage
- Authentication
- Functionality
- Image Handling
- Examples
- Troubleshooting
- API Reference
- Contributing
- License
To install the TMDB TypeScript Wrapper, follow these steps:
- Run the following command in your project directory:
// npm
npm install @tdanks2000/tmdb-wrapper
// yarn
yarn add @tdanks2000/tmdb-wrapper
// pnpm
pnpm i @tdanks2000/tmdb-wrapper
// bun
bun add @tdanks2000/tmdb-wrapperTo use the TMDB TypeScript API Wrapper in your TypeScript project, import the necessary classes and functions:
import { TMDB } from '@tdanks2000/tmdb-wrapper';Then, create an instance of the TMDB class, optionally providing an access token. Access tokens can be obtained from TMDb API Settings under read access token.
const tmdb = new TMDB('YOUR_ACCESS_TOKEN');You can now use the tmdb object to access various functionalities of the TMDB API. The wrapper provides access to all major TMDB API endpoints including Movies, TV Shows, People, Companies, Networks, and Watch Providers.
To use the TMDB API, you need to obtain an API key from TMDb API Settings. The wrapper supports both API key authentication and read access token authentication.
// Using API key
const tmdb = new TMDB({ apiKey: 'YOUR_API_KEY' });
// Using read access token (recommended)
const tmdb = new TMDB('YOUR_ACCESS_TOKEN');The TMDB Api Wrapper provides access to the following endpoints:
Access comprehensive information about movies, including details, credits, reviews, and more.
// Get popular movies
const popularMovies = await tmdb.movies.getPopular();
// Get movie details
const movieDetails = await tmdb.movies.getDetails(550); // Fight Club
// Get movie credits
const movieCredits = await tmdb.movies.getCredits(550);Retrieve information about TV shows, seasons, and episodes.
// Get popular TV shows
const popularShows = await tmdb.tvShows.getPopular();
// Get TV show details
const showDetails = await tmdb.tvShows.getDetails(1396); // Breaking Bad
// Get season details
const seasonDetails = await tmdb.tvSeasons.getDetails(1396, 1);
// Get episode details
const episodeDetails = await tmdb.tvEpisodes.getDetails(1396, 1, 1);Access information about actors, directors, and other people involved in movies and TV shows.
// Get popular people
const popularPeople = await tmdb.people.getPopular();
// Get person details
const personDetails = await tmdb.people.getDetails(287); // Brad Pitt
// Get person movie credits
const personMovieCredits = await tmdb.people.getMovieCredits(287);Retrieve information about production companies.
// Get company details
const companyDetails = await tmdb.companies.getDetails(1); // Lucasfilm
// Get company movies
const companyMovies = await tmdb.companies.getMovies(1);Access information about TV networks.
// Get network details
const networkDetails = await tmdb.networks.getDetails(213); // Netflix
// Get alternative names
const alternativeNames = await tmdb.networks.getAlternativeNames(213);Retrieve information about streaming platforms and availability.
// Get available regions
const regions = await tmdb.watchProviders.getAvailableRegions();
// Get movie providers
const movieProviders = await tmdb.watchProviders.getMovieProviders();
// Get TV providers
const tvProviders = await tmdb.watchProviders.getTvProviders();The wrapper also provides access to these additional endpoints:
- Account: Manage account details and settings
- Certifications: Retrieve certification information for movies and TV shows
- Changes: Get information about changes to the database
- Collections: Access information about movie collections
- Configuration: Retrieve configuration information for the API
- Credits: Get credits information for movies and TV shows
- Discover: Discover movies and TV shows based on various criteria
- Find: Find movies and TV shows by external IDs
- Genres: Retrieve information about movie and TV show genres
- Keywords: Access information about movie keywords
- Reviews: Get reviews for movies and TV shows
- Search: Search for movies, TV shows, and people
- Trending: Get trending movies and TV shows
The wrapper provides enhanced utilities for handling TMDB images:
import { getFullImagePath, ImageSizes, ImageFormats } from '@tdanks2000/tmdb-wrapper';
// Example usage for movie poster
const posterUrl = getFullImagePath(
'https://image.tmdb.org/t/p/',
ImageSizes.W500,
'/wwemzKWzjKYJFfCeiB57q3r4Bcm',
ImageFormats.JPG
);
// Results in: https://image.tmdb.org/t/p/w500/wwemzKWzjKYJFfCeiB57q3r4Bcm.jpg
// Example usage for profile image
const profileUrl = getFullImagePath(
'https://image.tmdb.org/t/p/',
ImageSizes.W185,
'/5XBzD5WuTyVQZeS4VI25z2moMeY.jpg',
ImageFormats.JPG
);
// Results in: https://image.tmdb.org/t/p/w185/5XBzD5WuTyVQZeS4VI25z2moMeY.jpgThe utility supports all TMDB image sizes and formats:
- Sizes: W45, W92, W154, W185, W300, W342, W500, W780, W1280, Original
- Formats: JPG, PNG, SVG
// Search for movies
const movieResults = await tmdb.search.searchMovies('Inception');
// Search for TV shows
const tvResults = await tmdb.search.searchTvShows('Breaking Bad');
// Search for people
const peopleResults = await tmdb.search.searchPeople('Brad Pitt');
// Multi-search (movies, TV shows, and people)
const multiResults = await tmdb.search.searchMulti('Marvel');// Get trending movies (day)
const trendingMoviesDay = await tmdb.trending.getTrendingMovies('day');
// Get trending TV shows (week)
const trendingTvWeek = await tmdb.trending.getTrendingTvShows('week');
// Get trending people (day)
const trendingPeopleDay = await tmdb.trending.getTrendingPeople('day');
// Get all trending content (week)
const trendingAllWeek = await tmdb.trending.getTrendingAll('week');// Discover movies by genre
const actionMovies = await tmdb.discover.discoverMovies({
with_genres: '28', // Action genre ID
sort_by: 'popularity.desc'
});
// Discover TV shows by network
const netflixShows = await tmdb.discover.discoverTvShows({
with_networks: '213', // Netflix network ID
sort_by: 'vote_average.desc'
});TMDb API has rate limiting in place. If you encounter rate limiting issues, consider implementing a delay between requests or using a caching mechanism.
// Example of implementing a delay between requests
const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
async function fetchWithDelay() {
const result1 = await tmdb.movies.getPopular();
await delay(250); // Wait 250ms between requests
const result2 = await tmdb.tvShows.getPopular();
return { movies: result1, tvShows: result2 };
}If you're experiencing authentication issues, ensure your API key or access token is valid and correctly formatted.
// Check if your token is valid
try {
const accountDetails = await tmdb.account.getDetails();
console.log('Authentication successful:', accountDetails);
} catch (error) {
console.error('Authentication failed:', error);
}For a complete list of available methods and parameters, please refer to the TMDB API Documentation.
This wrapper aims to provide a 1:1 mapping to the official TMDB API, with TypeScript types for improved developer experience.
Contributions are welcome! For bug reports, feature requests, or any other questions, please open an issue on the GitHub repository.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.