tmdbv3api

A lightweight Python library for The Movie Database (TMDb) API. The TMDb API is a resource for developers to integrate movie, TV show and cast data along with posters or movie fan art. themoviedb.org is a free and community edited database.

Register an account: https://www.themoviedb.org/account/signup

Check out the API documentation: https://developers.themoviedb.org/3/getting-started/introduction

Install

tmdbv3api is available on the Python Package Index (PyPI) at https://pypi.python.org/pypi/tmdbv3api

You can install tmdbv3api using setup.py.

$ python setup.py install

Usage

The first step is to initialize a TMDb object and set your API Key.

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

Alternatively, you can export your API key as an environment variable.

$ export TMDB_API_KEY='YOUR_API_KEY'

Other configuration settings include defining your language and enabling debug mode, for example:

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

Then to communicate with TMDb, create an instance of one of the objects and call that instances methods. For example, to retrieve movie recommendations for a given movie id:

from tmdbv3api import Movie

movie = Movie()

recommendations = movie.recommendations(movie_id=111)

for recommendation in recommendations:
    print(recommendation.title)
    print(recommendation.overview)

Examples

Get the list of popular movies on The Movie Database. This list refreshes every day.

movie = Movie()
popular = movie.popular()

for p in popular:
    print(p.id)
    print(p.title)
    print(p.overview)
    print(p.poster_path)

Get the primary information about a movie.

m = movie.details(343611)

print(m.title)
print(m.overview)
print(m.popularity)

Search for movies by title.

search = movie.search('Mad Max')

for res in search:
    print(res.id)
    print(res.title)
    print(res.overview)
    print(res.poster_path)
    print(res.vote_average)

Get the similar movies for a specific movie id.

similar = movie.similar(777)

for result in similar:
    print(result.title)
    print(result.overview)

Search for TV shows by title.

tv = TV()
show = tv.search('Breaking Bad')

for result in show:
    print(result.name)
    print(result.overview)

Get the similar TV shows for a specific tv id.

similar = tv.similar(1396)

for show in similar:
    print(show.name)
    print(show.overview)

Get the details of TV season for a specific tv id.

season = Season()
show_season = season.details(1396, 1)
print(show_season.air_date)
print(len(show_season.episodes))

Get the general person information for a specific id.

person = Person()
p = person.details(12)

print(p.name)
print(p.biography)

Get the person's id for the name:

Discover movies by different types of data like average rating, number of votes, genres and certifications.

# What movies are in theatres?

discover = Discover()
movie = discover.discover_movies({
    'primary_release_date.gte': '2017-01-20',
    'primary_release_date.lte': '2017-01-25'
})

# What are the most popular movies?

movie = discover.discover_movies({
    'sort_by': 'popularity.desc'
})

# What are the most popular kids movies?

movie = discover.discover_movies({
    'certification_country': 'US',
    'certification.lte': 'G',
    'sort_by': 'popularity.desc'
})

Discover TV shows by different types of data like average rating, number of votes, genres, the network they aired on and air dates.

# What are the most popular TV shows?

show = discover.discover_tv_shows({
    'sort_by': 'popularity.desc'
})

# What are the best dramas?

show = discover.discover_tv_shows({
    'with_genres': 18,
    'sort_by': 'vote_average.desc',
    'vote_count.gte': 10
})

Login to your account and add some movie recommendations to your TMDb watchlist.

from tmdbv3api import Account
from tmdbv3api import Authentication
from tmdbv3api import TMDb, Movie

USERNAME = "YOUR_USERNAME"
PASSWORD = "YOUR_PASSWORD"

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

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

account = Account()
details = account.details()

print("You are logged in as %s. Your account ID is %s." % (details.username, details.id))
print("This session expires at: %s" % auth.expires_at)

movie = Movie()

s = movie.search("Gangs of New York")
first_result = s[0]
recommendations = movie.recommendations(first_result.id)

for recommendation in recommendations:
    print("Adding %s (%s) to watchlist." % (recommendation.title, recommendation.release_date))
    account.add_to_watchlist(details.id, recommendation.id, "movie")

Running Tests

You can run the tests via the command line. You must export your TMDb API key as an environment variable. From the command line run:

$ export TMDB_API_KEY='YOUR_API_KEY'

Then run:

$ python -m unittest discover tests/