Skip to main content

tmdbv3api

Build Status codecov GitHub release (latest by date) PyPI Downloads GitHub commits since latest release (by date) for a branch

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 pip.

$ pip install tmdbv3api

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.

from tmdbv3api import Search

search = Search()
results = search.movies('Mad Max')

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

Search terms and filters are passed as arguments, not as a dictionary:

results = search.movies('Matrix', year=1999)   # correct
results = search.movies({'query': 'Matrix'})   # TypeError

If nothing matches, the results are empty rather than an error:

results = search.movies('something not found')
len(results)        # 0
list(results)       # []

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)

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")

Pagination

TMDb paginates most list and search endpoints: a response contains at most 20 items, and you can request at most 500 pages (10,000 items) per query. Methods that paginate accept a page argument, and the response exposes page, total_pages and total_results, so you need to loop to get everything.

company = Company()

movies = []
page = 1
while True:
    results = company.movies(882, page=page)
    movies.extend(results)
    if page >= int(results['total_pages']):
        break
    page += 1

Caching

Responses are cached in memory using an LRU cache that holds the most recent 128 requests. To change the size, set the TMDB_REQUEST_CACHE_MAXSIZE environment variable before importing the library (0 means unlimited, which means memory use grows with the number of distinct requests).

$ export TMDB_REQUEST_CACHE_MAXSIZE=512

You can also empty the cache at any time, or turn caching off completely:

tmdb.cache_clear()
tmdb.cache = False

Running Tests

You can run the tests via the command line. You must export your TMDb API key and Session ID as an environment variables.

Your Session ID can be obtained by running Authentication(username, password).session_id

Mac

$ export TMDB_API_KEY='YOUR_API_KEY'
$ export TMDB_SESSION_ID='YOUR_SESSION_ID'

Windows (Command Prompt)

$ setx TMDB_API_KEY "YOUR_API_KEY"
$ setx TMDB_SESSION_ID "YOUR_SESSION_ID"

Windows (PowerShell)

$ $Env:TMDB_API_KEY="YOUR_API_KEY"
$ $Env:TMDB_SESSION_ID="YOUR_SESSION_ID"

After you’ve set up your environmental variables then run:

$ python -m unittest discover tests/

Metadata

Release files for tmdbv3api 1.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tmdbv3api 1.10.0
File Size Uploaded Provenance Actions
tmdbv3api-1.10.0.tar.gz 28.5 kB Without provenance Details for tmdbv3api-1.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tmdbv3api 1.10.0
File Interpreter ABI Platform Actions
tmdbv3api-1.10.0-py3-none-any.whl Python 3 none any Details for tmdbv3api-1.10.0-py3-none-any.whl

Total release size: 55.0 kB

Release files / tmdbv3api-1.10.0.tar.gz

Download URL tmdbv3api-1.10.0.tar.gz
Size 28.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1fd343b60fe246185e2763253e442dd82998d37d0056759266b15d74b52a7024
BLAKE2b-256 checksum
How to use checksums
3d4dcb5c283abea93cca239d2eadb7182176162e51ee64c38b06260bdf3ae962
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / tmdbv3api-1.10.0-py3-none-any.whl

Download URL tmdbv3api-1.10.0-py3-none-any.whl
Size 26.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
95c72145dca4167d4e5013f45fc386102ecf35db69ef6c5bf60041621511f49e
BLAKE2b-256 checksum
How to use checksums
53a5440189ad51716c05cbe181c01dd0352db71a92abfff9610b854d145713a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for tmdbv3api 1.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.10.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page