This package is a TS wrapper client for The Movie Database API. It provides an easy way to use and access TMDB available apis at version 3.
// Using npm
npm i @leandrowkz/tmdb
// Using yarn
yarn add @leandrowkz/tmdb
Access the APIs through a single wrapper or by creating instances for each API.
import { TMDB } from '@leandrowkz/tmdb'
const tmdb = new TMDB({ apiKey: 'CREATED_ON_TMDB' })
const fightClub = await tmdb.movies.details(550)
console.log(fightClub)
{
"id": 550,
"imdb_id": "tt0137523",
"tagline": "How much can you know about yourself if you've never been in a fight?",
"title": "Fight Club",
"overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the way and ignites an out-of-control spiral toward oblivion.",
"backdrop_path": "/fCayJrkfRaCRCTh8GqN30f8oyQF.jpg",
"poster_path": null,
// ...
}
import { MoviesAPI } from '@leandrowkz/tmdb'
const movies = new MoviesAPI({ apiKey: 'CREATED_ON_TMDB' })
const fightClub = await movies.details(550)
console.log(fightClub)
{
"id": 550,
"imdb_id": "tt0137523",
"tagline": "How much can you know about yourself if you've never been in a fight?",
"title": "Fight Club",
"overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the way and ignites an out-of-control spiral toward oblivion.",
"backdrop_path": "/fCayJrkfRaCRCTh8GqN30f8oyQF.jpg",
"poster_path": null,
// ...
}
You can check how long each API call is taking to complete along with the URL called and the options.
Just set the property debug: true
on constructor payload. It works both on wrapper mode or using isolared APIs.
import { TMDB } from '@leandrowkz/tmdb'
const tmdb = new TMDB({ apiKey: 'TMDB_APIKEY', debug: true })
await tmdb.movies.details(550)
await tmdb.list.details(440)
await tmdb.search.keyword()
Your terminal should print debug lines similar to this:
🍿 TMDB DEBUGGER: https:/api.themoviedb.org/3/movie/popular?api_key=TMDB_APIKEY with params {"method":"GET","headers":{},"body":null}: 159.737ms
🍿 TMDB DEBUGGER: https:/api.themoviedb.org/3/discover/movie?with_genres=10751&api_key=TMDB_APIKEY with params {"method":"GET","headers":{},"body":null}: 201.322ms
🍿 TMDB DEBUGGER: https:/api.themoviedb.org/3/movie/now_playing?api_key=TMDB_APIKEY with params {"method":"GET","headers":{},"body":null}: 258.441ms
You can handle TMDB API errors like not found or unauthorized by wrapping calls under a try/catch
, like:
import { MoviesAPI, TMDBResponseError } from '@leandrowkz/tmdb'
try {
await api.details(1)
} catch (e) {
if (e instanceof TMDBResponseError) {
console.log(e.getResponse())
// {
// status: 'Not Found',
// status_code: 34,
// status_message: 'The resource you requested could not be found.'
// }
}
}
This library provides classes to access all TMDB APIs on version 3. The following list shows all library APIs, how to use them and the available methods. Click on the API you want to see to check the API documentation.
Since this package is written on TS you will get autocomplete out of the box.
API | Access using wrapper | Status |
---|---|---|
Account | tmdb.account.* |
âś… |
Authentication | tmdb.authentication.* |
âś… |
Certifications | tmdb.certifications.* |
âś… |
Changes | tmdb.changes.* |
âś… |
Collections | tmdb.collections.* |
âś… |
Companies | tmdb.certifications.* |
âś… |
Configuration | tmdb.configuration.* |
âś… |
Credits | tmdb.credits.* |
âś… |
Discover | tmdb.discover.* |
âś… |
Find | tmdb.find.* |
âś… |
Genres | tmdb.genres.* |
âś… |
Guest Sessions | tmdb.guestSessions.* |
âś… |
Keywords | tmdb.keywords.* |
âś… |
Lists | tmdb.lists.* |
âś… |
Movies | tmdb.movies.* |
âś… |
Networks | tmdb.networks.* |
âś… |
Trending | tmdb.trending.* |
âś… |
People | tmdb.people.* |
âś… |
Reviews | tmdb.reviews.* |
âś… |
Search | tmdb.search.* |
âś… |
TV | tmdb.tv.* |
âś… |
TV Episodes | tmdb.tvEpisodes.* |
âś… |
TV Seasons | tmdb.tvSeasons.* |
âś… |
TV Episode Groups | tmdb.tvEpisodeGroups.* |
âś… |
Watch Providers | tmdb.watchProviders.* |
âś… |
TMDB documentation: https://developers.themoviedb.org/3/account
import { AccountAPI } from '@leandrowkz/tmdb'
const account = new AccountAPI({ apiKey: 'TMDB_APIKEY' })
account.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
filters: DetailsFilters |
https://developers.themoviedb.org/3/account/get-account-details |
createdLists |
accountId: number filters: CreatedListsFilters |
https://developers.themoviedb.org/3/account/get-created-lists |
favoriteMovies |
accountId: number filters: FavoriteMoviesFilters |
https://developers.themoviedb.org/3/account/get-favorite-movies |
favoriteTVShows |
accountId: number filters: FavoriteTVShowsFilters |
https://developers.themoviedb.org/3/account/get-favorite-tv-shows |
markAsFavorite |
accountId: number data: MarkAsFavoriteBody filters: MarkAsFavoriteFilters |
https://developers.themoviedb.org/3/account/mark-as-favorite |
ratedMovies |
accountId: number filters: RatedMoviesFilters |
https://developers.themoviedb.org/3/account/get-rated-movies |
ratedTVShows |
accountId: number filters: RatedTVShowsFilters |
https://developers.themoviedb.org/3/account/get-rated-tv-shows |
ratedTVEpisodes |
accountId: number filters: RatedTVEpisodesFilters |
https://developers.themoviedb.org/3/account/get-rated-tv-episodes |
movieWatchlist |
accountId: number filters: MovieWatchlistFilters |
https://developers.themoviedb.org/3/account/get-movies-watchlist |
tvShowWatchlist |
accountId: number filters: TVShowWatchlistFilters |
https://developers.themoviedb.org/3/account/get-tv-show-watchlist |
addToWatchlist |
accountId: number data: AddToWatchlistBody filters: AddToWatchlistFilters |
https://developers.themoviedb.org/3/account/add-to-watchlist |
TMDB documentation: https://developers.themoviedb.org/3/authentication
import { AuthenticationAPI } from '@leandrowkz/tmdb'
const auth = new AuthenticationAPI({ apiKey: 'TMDB_APIKEY' })
auth.*
Methods | Parameters | TMDB docs |
---|---|---|
createGuestSession |
- |
https://developers.themoviedb.org/3/authentication/create-guest-session |
createRequestToken |
- |
https://developers.themoviedb.org/3/authentication/create-request-token |
createSession |
data: CreateSessionBody |
https://developers.themoviedb.org/3/authentication/create-session |
createSessionWithLogin |
data: CreateSessionWithLoginBody |
https://developers.themoviedb.org/3/authentication/validate-request-token |
createSessionConvertV4 |
data: CreateSessionConvertV4Body |
https://developers.themoviedb.org/3/authentication/create-session-from-v4-access-token |
deleteSession |
data: DeleteSessionBody |
https://developers.themoviedb.org/3/authentication/delete-session |
TMDB documentation: https://developers.themoviedb.org/3/certifications
import { CertificationsAPI } from '@leandrowkz/tmdb'
const certifications = new CertificationsAPI({ apiKey: 'TMDB_APIKEY' })
certifications.*
Methods | Parameters | TMDB docs |
---|---|---|
movie |
- |
https://developers.themoviedb.org/3/certifications/get-movie-certifications |
tv |
- |
https://developers.themoviedb.org/3/certifications/get-tv-certifications |
TMDB documentation: https://developers.themoviedb.org/3/changes
import { ChangesAPI } from '@leandrowkz/tmdb'
const changes = new ChangesAPI({ apiKey: 'TMDB_APIKEY' })
changes.*
Methods | Parameters | TMDB docs |
---|---|---|
movie |
filters?: ChangesFilters |
https://developers.themoviedb.org/3/changes/get-movie-change-list |
tv |
filters?: ChangesFilters |
https://developers.themoviedb.org/3/changes/get-tv-change-list |
person |
filters?: ChangesFilters |
https://developers.themoviedb.org/3/changes/get-person-change-list |
TMDB documentation: https://developers.themoviedb.org/3/collections
import { CollectionsAPI } from '@leandrowkz/tmdb'
const collections = new CollectionsAPI({ apiKey: 'TMDB_APIKEY' })
collections.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
collectionId: number filters?: CollectionsFilters |
https://developers.themoviedb.org/3/collections/get-collection-details |
images |
collectionId: number filters?: CollectionsFilters |
https://developers.themoviedb.org/3/collections/get-collection-images |
translations |
collectionId: number filters?: CollectionsFilters |
https://developers.themoviedb.org/3/collections/get-collection-translations |
TMDB documentation: https://developers.themoviedb.org/3/companies
import { CompaniesAPI } from '@leandrowkz/tmdb'
const companies = new CompaniesAPI({ apiKey: 'TMDB_APIKEY' })
companies.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
companyId: number |
https://developers.themoviedb.org/3/companies/get-company-details |
alternativeNames |
companyId: number |
https://developers.themoviedb.org/3/companies/get-company-alternative-names |
images |
companyId: number |
https://developers.themoviedb.org/3/companies/get-company-images |
TMDB documentation: https://developers.themoviedb.org/3/configuration
import { ConfigurationAPI } from '@leandrowkz/tmdb'
const configs = new ConfigurationAPI({ apiKey: 'TMDB_APIKEY' })
configs.*
Methods | Parameters | TMDB docs |
---|---|---|
configuration |
- |
https://developers.themoviedb.org/3/configuration/get-api-configuration |
countries |
- |
https://developers.themoviedb.org/3/configuration/get-countries |
jobs |
- |
https://developers.themoviedb.org/3/configuration/get-jobs |
languages |
- |
https://developers.themoviedb.org/3/configuration/get-languages |
primaryTranslations |
- |
https://developers.themoviedb.org/3/configuration/get-primary-translations |
timezones |
- |
https://developers.themoviedb.org/3/configuration/get-timezones |
TMDB documentation: https://developers.themoviedb.org/3/credits
import { CreditsAPI } from '@leandrowkz/tmdb'
const credits = new CreditsAPI({ apiKey: 'TMDB_APIKEY' })
credits.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
creditId: number |
https://developers.themoviedb.org/3/credits/get-details |
TMDB documentation: https://developers.themoviedb.org/3/discover
import { ConfigurationAPI } from '@leandrowkz/tmdb'
const discover = new DiscoverAPI({ apiKey: 'TMDB_APIKEY' })
discover.*
Methods | Parameters | TMDB docs |
---|---|---|
movies |
filters?: MovieFilters |
https://developers.themoviedb.org/3/discover/movie-discover |
tv |
filters?: TVShowFilters |
https://developers.themoviedb.org/3/discover/tv-discover |
TMDB documentation: https://developers.themoviedb.org/3/find
import { FindAPI } from '@leandrowkz/tmdb'
const find = new FindAPI({ apiKey: 'TMDB_APIKEY' })
find.*
Methods | Parameters | TMDB docs |
---|---|---|
find |
externalId: string filters: FindFilters |
https://developers.themoviedb.org/3/find/find-by-id |
TMDB documentation: https://developers.themoviedb.org/3/genres
import { GenresAPI } from '@leandrowkz/tmdb'
const genres = new GenresAPI({ apiKey: 'TMDB_APIKEY' })
genres.*
Methods | Parameters | TMDB docs |
---|---|---|
movie |
filters?: GenresFilters |
https://developers.themoviedb.org/3/genres/get-movie-list |
tv |
filters?: GenresFilters |
https://developers.themoviedb.org/3/genres/get-tv-list |
TMDB documentation: https://developers.themoviedb.org/3/guest-sessions
import { GuestSessionsAPI } from '@leandrowkz/tmdb'
const guestSessions = new GuestSessionsAPI({ apiKey: 'TMDB_APIKEY' })
guestSessions.*
Methods | Parameters | TMDB docs |
---|---|---|
ratedMovies |
guestSessionId: string filters?: RatedFilters |
https://developers.themoviedb.org/3/guest-sessions/get-guest-session-rated-movies |
ratedTVShows |
guestSessionId: string filters?: RatedFilters |
https://developers.themoviedb.org/3/guest-sessions/get-guest-session-rated-tv-shows |
ratedTVEpisodes |
guestSessionId: string filters?: RatedFilters |
https://developers.themoviedb.org/3/guest-sessions/get-guest-session-rated-tv-episodes |
TMDB documentation: https://developers.themoviedb.org/3/keywords
import { KeywordsAPI } from '@leandrowkz/tmdb'
const keywords = new GenresAPI({ apiKey: 'TMDB_APIKEY' })
keywords.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
keywordId: string |
https://developers.themoviedb.org/3/keywords/get-keyword-details |
movies |
keywordId: string filters?: MoviesFilters |
https://developers.themoviedb.org/3/keywords/get-movies-by-keyword |
TMDB documentation: https://developers.themoviedb.org/3/lists
import { ListsAPI } from '@leandrowkz/tmdb'
const lists = new ListsAPI({ apiKey: 'TMDB_APIKEY' })
lists.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
`listId: string | number<br/> filters?: DetailsFilters` |
itemStatus |
`listId: string | number<br/> filters: ItemStatusFilters` |
create |
data: CreateListBody filters: CreateListFilters |
https://developers.themoviedb.org/3/lists/create-list |
addItem |
`listId: string | number<br/> data: AddItemBody<br/> filters: AddItemFilters` |
removeItem |
`listId: string | number<br/> data: RemoveItemBody<br/> filters: RemoveItemFilters` |
clear |
`listId: string | number<br/> filters: ClearListFilters` |
remove |
`listId: string | number<br/> filters: DeleteListFilters` |
TMDB documentation: https://developers.themoviedb.org/3/movies
import { MoviesAPI } from '@leandrowkz/tmdb'
const movies = new MoviesAPI({ apiKey: 'TMDB_APIKEY' })
movies.*
TMDB documentation: https://developers.themoviedb.org/3/networks
import { NetworksAPI } from '@leandrowkz/tmdb'
const networks = new NetworksAPI({ apiKey: 'TMDB_APIKEY' })
networks.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
networkId: number |
https://developers.themoviedb.org/3/networks/get-network-details |
alternativeNames |
networkId: number |
https://developers.themoviedb.org/3/networks/get-network-alternative-names |
images |
networkId: number |
https://developers.themoviedb.org/3/networks/get-network-images |
TMDB documentation: https://developers.themoviedb.org/3/people
import { PeopleAPI } from '@leandrowkz/tmdb'
const people = new PeopleAPI({ apiKey: 'TMDB_APIKEY' })
people.*
TMDB documentation: https://developers.themoviedb.org/3/reviews
import { ReviewsAPI } from '@leandrowkz/tmdb'
const reviews = new ReviewsAPI({ apiKey: 'TMDB_APIKEY' })
reviews.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
reviewId: string |
https://developers.themoviedb.org/3/reviews/get-review-details |
TMDB documentation: https://developers.themoviedb.org/3/search
import { SearchAPI } from '@leandrowkz/tmdb'
const search = new SearchAPI({ apiKey: 'TMDB_APIKEY' })
search.*
Methods | Parameters | TMDB docs |
---|---|---|
companies |
filters: SearchFilters |
https://developers.themoviedb.org/3/search/search-companies |
collections |
filters: CollectionsFilters |
https://developers.themoviedb.org/3/search/search-collections |
keywords |
filters: SearchFilters |
https://developers.themoviedb.org/3/search/search-keywords |
movies |
filters: MoviesFilters |
https://developers.themoviedb.org/3/search/search-movies |
multiSearch |
filters: MultiSearchFilters |
https://developers.themoviedb.org/3/search/multi-search |
people |
filters: PeopleFilters |
https://developers.themoviedb.org/3/search/search-people |
tvShows |
filters: TVShowsFilters |
https://developers.themoviedb.org/3/search/search-tv-shows |
TMDB documentation: https://developers.themoviedb.org/3/trending
import { TrendingAPI } from '@leandrowkz/tmdb'
const trending = new TrendingAPI({ apiKey: 'TMDB_APIKEY' })
trending.*
Methods | Parameters | TMDB docs |
---|---|---|
getTrending |
`mediaType: 'all' | 'movie' |
TMDB documentation: https://developers.themoviedb.org/3/tv
import { TVShowsAPI } from '@leandrowkz/tmdb'
const tv = new TVShowsAPI({ apiKey: 'TMDB_APIKEY' })
tv.*
TMDB documentation: https://developers.themoviedb.org/3/tv-episode-groups/
import { TVEpisodeGroupsAPI } from '@leandrowkz/tmdb'
const tvEpisodeGroups = new TVEpisodeGroupsAPI({ apiKey: 'TMDB_APIKEY' })
tvEpisodeGroups.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
episodeGroupId: number filters?: DetailsFilters |
https://developers.themoviedb.org/3/tv-episode-groups/get-tv-episode-group-details |
TMDB documentation: https://developers.themoviedb.org/3/tv-episodes
import { TVEpisodesAPI } from '@leandrowkz/tmdb'
const tvEpisodes = new TVEpisodesAPI({ apiKey: 'TMDB_APIKEY' })
tvEpisodes.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
tvShowId: number season: number episode: number filters?: DetailsFilters |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-details |
accountStates |
tvShowId: number season: number episode: number filters?: AccountStatesFilters |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-account-states |
changes |
tvShowId: number filters?: ChangesFilters |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-changes |
credits |
tvShowId: number season: number episode: number filters?: CreditsFilters |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-credits |
externalIds |
tvShowId: number season: number episode: number |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-external-ids |
images |
tvShowId: number season: number episode: number filters?: ImagesFilters |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-images |
translations |
tvShowId: number season: number episode: number |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-translations |
videos |
tvShowId: number season: number episode: number filters?: VideosFilters |
https://developers.themoviedb.org/3/tv-episodes/get-tv-episode-videos |
rateTVEpisode |
tvShowId: number season: number episode: number body: RateBody filters?: RateFilters |
https://developers.themoviedb.org/3/tv-episodes/rate-tv-episode |
deleteTVEpisodeRate |
tvShowId: number season: number episode: number filters?: RateFilters |
https://developers.themoviedb.org/3/tv-episodes/delete-tv-episode-rating |
TMDB documentation: https://developers.themoviedb.org/3/tv-seasons
import { TVSeasonsAPI } from '@leandrowkz/tmdb'
const tvSeasons = new TVSeasonsAPI({ apiKey: 'TMDB_APIKEY' })
tvSeasons.*
Methods | Parameters | TMDB docs |
---|---|---|
details |
tvShowId: number seasonNumber: number filters?: DetailsFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-details |
accountStates |
tvShowId: number seasonNumber: number filters?: AccountStatesFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-account-states |
aggregateCredits |
tvShowId: number seasonNumber: number filters?: AggregateCreditsFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-aggregate-credits |
changes |
tvShowId: number seasonNumber: number filters?: ChangesFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-changes |
credits |
tvShowId: number seasonNumber: number filters?: CreditsFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-credits |
externalIds |
tvShowId: number seasonNumber: number filters?: ExternalIdsFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-external-ids |
images |
tvShowId: number seasonNumber: number filters?: ImagesFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-images |
translations |
tvShowId: number seasonNumber: number filters?: TranslationFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-translations |
videos |
tvShowId: number seasonNumber: number filters?: VideosFilters |
https://developers.themoviedb.org/3/tv-seasons/get-tv-season-videos |
TMDB documentation: https://developers.themoviedb.org/3/watch-providers
import { WatchProvidersAPI } from '@leandrowkz/tmdb'
const wp = new WatchProvidersAPI({ apiKey: 'TMDB_APIKEY' })
wp.*
Methods | Parameters | TMDB docs |
---|---|---|
availableRegions |
filters?: AvailableRegionsFilters |
https://developers.themoviedb.org/3/watch-providers/get-available-regions |
movieProviders |
filters?: WatchProvidersFilters |
https://developers.themoviedb.org/3/watch-providers/get-movie-providers |
tvProviders |
filters?: WatchProvidersFilters |
https://developers.themoviedb.org/3/watch-providers/get-tv-providers |