Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A Python wrapper for The Movie Database API v3

Project Description

A wrapper for The Movie Database API v3

tmdbsimple is a wrapper, written in Python, for The Movie Database (TMDb) API v3. By calling the functions available in tmdbsimple you can simplify your code and easily access a vast amount of movie, tv, and cast data. To learn more about The Movie Database API, check out the overview page and documentation page


  • COMPLETELY UPDATED AND FULLY TESTED. Updated with the latest Account, Authentication, Certification, GuestSession, List, Movie, People, Timezones, TV, TV Season, and TV Episode methods.
  • Supports and tested under Python 2.7.6, 3.3.5, and 3.4.0
  • One-to-one mapping between tmdbsimple functions and TMDb methods.
  • Implements all TMDb methods, including Accounts and Authentication.
  • Implements new TV features.
  • Easy to access data using Python class attributes.
  • Easy to experiment with tmdbsimple functions inside the Python interpreter.
  • Code tested with unittests, which illustrate the function call syntax.


tmdbsimple is available on the Python Package Index (PyPI) at

You can install tmdbsimple 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 the source from Github and install it yourself

If you install it yourself, also install requests.


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

  1. Register for and verify an account.
  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 the tmdbsimple package installed and a TMDb API key, you can start to play with the data.

First, import the library and assign your API_KEY.

>>> import tmdbsimple as tmdb

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

>>> movie = tmdb.Movies(603)
>>> response =
>>> movie.title
'The Matrix'
>>> movie.budget
>>> response = movie.releases()
>>> for c in movie.countries:
...    if c['iso_3166_1'] == 'US':
...         print(c['certification'])

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

>>> search = tmdb.Search()
>>> response ='The Bourne')
>>> for s in search.results:
...     print(s['title'], s['id'], s['release_date'], s['popularity'])
The Bourne Ultimatum 2503 2007-08-03 55.2447062124256
The Bourne Supremacy 2502 2004-07-23 43.4553609681985
The Bourne Identity 2501 2002-06-06 38.5531563780592
The Bourne Legacy 49040 2012-08-10 9.90635210153143
The Bourne Identity 8677 1988-05-08 1.53988446573129
Bette Bourne: It Goes with the Shoes 179304  0.23

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

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

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

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

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

If you use Authentication to access a user Account, be sure to check out

If you like this wrapper, and would like access to even more movie and TV data, check out rtsimple, a wrapper for the Rotten Tomatoes API.

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
tmdbsimple-1.8.0-py2.py3-none-any.whl (23.9 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Oct 23, 2017
tmdbsimple-1.8.0.tar.gz (16.0 kB) Copy SHA256 Checksum SHA256 Source Oct 23, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting