Repository files navigation

tmdbsimple is a wrapper, written in Python, for The Movie Database (TMDb) APIv3. By calling the functions available intmdbsimple you can simplify yourcode and easily access a vast amount of movie, tv, and cast data. To learnmore about The Movie Database API, check out theoverview anddocumentation.

• COMPLETELY UPDATED AND FULLY TESTED.
• Supports onlyPython versions with TLS1.2.Keep it simple!
• Tested with Python 3.9, 3.10, and 3.11.
• One-to-one mapping betweentmdbsimple methods and TMDb endpoints.
• Implements all TMDb methods, including Accounts and Authentication.
• Easy to access data using Python class attributes.
• Easy to experiment withtmdbsimple functions inside the Python interpreter.
• Code tested with unittests. Refer to the unittest code for method call syntax.

tmdbsimple is available on the Python Package Index (PyPI) athttps://pypi.python.org/pypi/tmdbsimple.

You can installtmdbsimple using one of the following techniques.

• Use pip:

pip install tmdbsimple

• Download the .zip or .tar.gz file from PyPI and install it yourself
• Download thesource from Github andinstall it yourself

If you install it yourself, also installrequests.

You will need an API key to The Movie Database to access the API. To obtain akey, follow these steps:

1. Register for and verify anaccount.
2. Log into your account.
3. Select the API section on left side of your account page.
4. Click on the link to generate a new API key and follow the instructions.

Once you have thetmdbsimple package installed and a TMDb API key, you canstart to play with the data.

First, import the library and assign your API_KEY.

importtmdbsimpleastmdbtmdb.API_KEY='YOUR_API_KEY_HERE'

Optionally, set a timeout for requests. Seehere for more info.

tmdb.REQUESTS_TIMEOUT=5# seconds, for both connect and read

or

tmdb.REQUESTS_TIMEOUT= (2,5)# seconds, for connect and read specifically

Optionally, configure the library to use your own REQUESTS_SESSION. Seehere for more info.

importrequeststmdb.REQUESTS_SESSION=requests.Session()

To communicate with The Movie Database API, create an instance of one of theobject types, call one of the methods on the instance, and access the instanceattributes. Use keys to access the values of attributes that are dictionaries.In this example, we create a movie instance for 'The Matrix' and determine thebudget and certification.

>>>movie=tmdb.Movies(603)>>>response=movie.info()>>>movie.title'The Matrix'>>>movie.budget63000000>>>response=movie.releases()>>>forcinmovie.countries:    ...ifc['iso_3166_1']=='US':    ...print(c['certification'])    ...'R'

Let's play with the interface a bit more. Suppose you and your friend arearguing over which movie in the Bourne series was most popular. Your friendsays the first in a series is always most popular. You disagree.

>>>search=tmdb.Search()>>>response=search.movie(query='The Bourne')>>>forsinsearch.results:    ...print(s['title'],s['id'],s['release_date'],s['popularity'])    ...TheBourneUltimatum25032007-08-0355.2447062124256TheBourneSupremacy25022004-07-2343.4553609681985TheBourneIdentity25012002-06-0638.5531563780592TheBourneLegacy490402012-08-109.90635210153143TheBourneIdentity86771988-05-081.53988446573129BetteBourne:ItGoeswiththeShoes1793040.23

You are correct! Now you claim the producers should be able to make sequelscheaper, based on what they learned from making the first movie. To be fair,you compute the budget per minute of runtime. Your friend disagrees, claimingthe producers spend more money trying to out do the previous sequel.

>>>identity=tmdb.Movies(2501)>>>response=identity.info()>>>identity.budget,identity.runtime    (60000000,119)>>>int(identity.budget/identity.runtime)504201>>>supremacy=tmdb.Movies(2502)>>>response=supremacy.info()>>>supremacy.budget,supremacy.runtime    (75000000,108)>>>int(supremacy.budget/supremacy.runtime)694444>>>ultimatum=tmdb.Movies(2503)>>>response=ultimatum.info()>>>ultimatum.budget,ultimatum.runtime    (70000000,115)>>>int(ultimatum.budget/ultimatum.runtime)608695

In this case you are both correct. The third movie was cheaper than thesecond, which was more expensive than the first.

You also can call one of the methods without explicitly instanciating anobject.

>>>response=tmdb.Movies(603).info()>>>response['budget']63000000

If you use Authentication to access a user Account, be sure to check outhttps://www.themoviedb.org/documentation/api/sessions.

If you like this wrapper, and would like access to even more movie and TV data,check outrtsimplehttps://pypi.python.org/pypi/rtsimple, a wrapper for theRotten Tomatoes API.