📦 🎥 TMDB TypeScript client

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.

Installation

// Using npm
npm i @leandrowkz/tmdb

// Using yarn
yarn add @leandrowkz/tmdb

Basic usage

Access the APIs through a single wrapper or by creating instances for each API.

Using wrapper

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,
  // ...
}

Using isolated APIs

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,
  // ...
}

Debugging

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

Handling errors

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.'
    // }
  }
}

Available APIs

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.

Account API

TMDB documentation: https://developers.themoviedb.org/3/account

import { AccountAPI } from '@leandrowkz/tmdb'

const account = new AccountAPI({ apiKey: 'TMDB_APIKEY' })

account.*

Authentication API

TMDB documentation: https://developers.themoviedb.org/3/authentication

import { AuthenticationAPI } from '@leandrowkz/tmdb'

const auth = new AuthenticationAPI({ apiKey: 'TMDB_APIKEY' })

auth.*

Certifications API

TMDB documentation: https://developers.themoviedb.org/3/certifications

import { CertificationsAPI } from '@leandrowkz/tmdb'

const certifications = new CertificationsAPI({ apiKey: 'TMDB_APIKEY' })

certifications.*

Changes API

TMDB documentation: https://developers.themoviedb.org/3/changes

import { ChangesAPI } from '@leandrowkz/tmdb'

const changes = new ChangesAPI({ apiKey: 'TMDB_APIKEY' })

changes.*

Collections API

TMDB documentation: https://developers.themoviedb.org/3/collections

import { CollectionsAPI } from '@leandrowkz/tmdb'

const collections = new CollectionsAPI({ apiKey: 'TMDB_APIKEY' })

collections.*

Companies API

TMDB documentation: https://developers.themoviedb.org/3/companies

import { CompaniesAPI } from '@leandrowkz/tmdb'

const companies = new CompaniesAPI({ apiKey: 'TMDB_APIKEY' })

companies.*

Configuration API

TMDB documentation: https://developers.themoviedb.org/3/configuration

import { ConfigurationAPI } from '@leandrowkz/tmdb'

const configs = new ConfigurationAPI({ apiKey: 'TMDB_APIKEY' })

configs.*

Credits API

TMDB documentation: https://developers.themoviedb.org/3/credits

import { CreditsAPI } from '@leandrowkz/tmdb'

const credits = new CreditsAPI({ apiKey: 'TMDB_APIKEY' })

credits.*

Discover API

TMDB documentation: https://developers.themoviedb.org/3/discover

import { ConfigurationAPI } from '@leandrowkz/tmdb'

const discover = new DiscoverAPI({ apiKey: 'TMDB_APIKEY' })

discover.*

Find API

TMDB documentation: https://developers.themoviedb.org/3/find

import { FindAPI } from '@leandrowkz/tmdb'

const find = new FindAPI({ apiKey: 'TMDB_APIKEY' })

find.*

Genres API

TMDB documentation: https://developers.themoviedb.org/3/genres

import { GenresAPI } from '@leandrowkz/tmdb'

const genres = new GenresAPI({ apiKey: 'TMDB_APIKEY' })

genres.*

Guest Sessions API

TMDB documentation: https://developers.themoviedb.org/3/guest-sessions

import { GuestSessionsAPI } from '@leandrowkz/tmdb'

const guestSessions = new GuestSessionsAPI({ apiKey: 'TMDB_APIKEY' })

guestSessions.*

Keywords API

TMDB documentation: https://developers.themoviedb.org/3/keywords

import { KeywordsAPI } from '@leandrowkz/tmdb'

const keywords = new GenresAPI({ apiKey: 'TMDB_APIKEY' })

keywords.*

Lists API

TMDB documentation: https://developers.themoviedb.org/3/lists

import { ListsAPI } from '@leandrowkz/tmdb'

const lists = new ListsAPI({ apiKey: 'TMDB_APIKEY' })

lists.*

Movies API

TMDB documentation: https://developers.themoviedb.org/3/movies

import { MoviesAPI } from '@leandrowkz/tmdb'

const movies = new MoviesAPI({ apiKey: 'TMDB_APIKEY' })

movies.*

Networks API

TMDB documentation: https://developers.themoviedb.org/3/networks

import { NetworksAPI } from '@leandrowkz/tmdb'

const networks = new NetworksAPI({ apiKey: 'TMDB_APIKEY' })

networks.*

People API

TMDB documentation: https://developers.themoviedb.org/3/people

import { PeopleAPI } from '@leandrowkz/tmdb'

const people = new PeopleAPI({ apiKey: 'TMDB_APIKEY' })

people.*

Reviews API

TMDB documentation: https://developers.themoviedb.org/3/reviews

import { ReviewsAPI } from '@leandrowkz/tmdb'

const reviews = new ReviewsAPI({ apiKey: 'TMDB_APIKEY' })

reviews.*

Search API

TMDB documentation: https://developers.themoviedb.org/3/search

import { SearchAPI } from '@leandrowkz/tmdb'

const search = new SearchAPI({ apiKey: 'TMDB_APIKEY' })

search.*

Trending API

TMDB documentation: https://developers.themoviedb.org/3/trending

import { TrendingAPI } from '@leandrowkz/tmdb'

const trending = new TrendingAPI({ apiKey: 'TMDB_APIKEY' })

trending.*

TV Shows API

TMDB documentation: https://developers.themoviedb.org/3/tv

import { TVShowsAPI } from '@leandrowkz/tmdb'

const tv = new TVShowsAPI({ apiKey: 'TMDB_APIKEY' })

tv.*

TV Episode Groups API

TMDB documentation: https://developers.themoviedb.org/3/tv-episode-groups/

import { TVEpisodeGroupsAPI } from '@leandrowkz/tmdb'

const tvEpisodeGroups = new TVEpisodeGroupsAPI({ apiKey: 'TMDB_APIKEY' })

tvEpisodeGroups.*

TV Episodes API

TMDB documentation: https://developers.themoviedb.org/3/tv-episodes

import { TVEpisodesAPI } from '@leandrowkz/tmdb'

const tvEpisodes = new TVEpisodesAPI({ apiKey: 'TMDB_APIKEY' })

tvEpisodes.*

TV Seasons API

TMDB documentation: https://developers.themoviedb.org/3/tv-seasons

import { TVSeasonsAPI } from '@leandrowkz/tmdb'

const tvSeasons = new TVSeasonsAPI({ apiKey: 'TMDB_APIKEY' })

tvSeasons.*

Watch Providers API

TMDB documentation: https://developers.themoviedb.org/3/watch-providers

import { WatchProvidersAPI } from '@leandrowkz/tmdb'

const wp = new WatchProvidersAPI({ apiKey: 'TMDB_APIKEY' })

wp.*