tmdbv3api Python Library

Install the library using the Python Package Index (PyPI) with pip.

$ pip install tmdbv3api

To use the library, you must first initialize a TMDb object and provide your API key. You can set the key directly on the object or export it as an environment variable named TMDB_API_KEY.

from tmdbv3api import TMDb
tmdb = TMDb()
tmdb.api_key = 'YOUR_API_KEY'

You can customize the TMDb instance by setting the language and enabling debug mode.

tmdb.language = 'en'
tmdb.debug = True

The Person class allows you to retrieve general information and biographies for individuals in the TMDb database.

from tmdbv3api import Person

person = Person()
p = person.details(12)
print(p.name)
print(p.biography)

You can authenticate using your TMDb username and password via the Authentication class to perform account-specific actions, such as adding movies to a watchlist using the Account class.

from tmdbv3api import Account, Authentication, TMDb, Movie

USERNAME = "YOUR_USERNAME"
PASSWORD = "YOUR_PASSWORD"

tmdb = TMDb()
tmdb.api_key = "YOUR_API_KEY"

# Authenticate
auth = Authentication(username=USERNAME, password=PASSWORD)

# Access account details
account = Account()
details = account.details()

# Add a movie to watchlist
movie = Movie()
s = movie.search("Gangs of New York")
first_result = s[0]
account.add_to_watchlist(details.id, first_result.id, "movie")

The Movie class allows you to interact with movie data. You can search for movies by title, get specific movie details by ID, find popular movies, or find similar movies.

from tmdbv3api import Movie

movie = Movie()

# Search for movies
search = movie.search('Mad Max')

# Get popular movies
popular = movie.popular()

# Get details for a specific movie ID
m = movie.details(343611)

# Get similar movies for a specific movie ID
similar = movie.similar(777)

# Get recommendations for a specific movie ID
recommendations = movie.recommendations(movie_id=111)

The TV class provides access to TV show data, including searching by title, finding similar shows, and retrieving season details via the Season class.

from tmdbv3api import TV, Season

tv = TV()

# Search for TV shows
show = tv.search('Breaking Bad')

# Get similar TV shows
similar = tv.similar(1396)

# Get details of a specific TV season
season = Season()
show_season = season.details(1396, 1)

The Discover class allows you to find movies and TV shows based on specific filters like release dates, popularity, genres, or certifications.

from tmdbv3api import Discover

discover = Discover()

# Discover movies by release date range
movies = discover.discover_movies({
    'primary_release_date.gte': '2017-01-20',
    'primary_release_date.lte': '2017-01-25'
})

# Discover movies sorted by popularity
popular_movies = discover.discover_movies({
    'sort_by': 'popularity.desc'
})

# Discover TV shows by genre and vote count
tv_shows = discover.discover_tv_shows({
    'with_genres': 18,
    'sort_by': 'vote_average.desc',
    'vote_count.gte': 10
})