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

A simple wrapper for the TMDb API.

Project Description

A lightweight Python wrapper for The Movie Database (TMDb) API. This library allows users to interact with the API and retrieve data on movies, TV shows and actors.

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

Check out the API documentation: https://docs.themoviedb.apiary.io

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 api_key='YOUR_API_KEY'

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)

The objects currently implemented are Movie, TV, Person and Discover.

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

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 api_key='YOUR_API_KEY'

Then run:

$ python -m unittest discover tests/

Supported Methods

Movies

  • /movie/latest
  • /movie/now_playing
  • /movie/top_rated
  • /movie/upcoming
  • /movie/id
  • /movie/id/similar
  • /movie/id/recommendations
  • /movie/id/videos
  • /movie/id/reviews
  • /movie/id/lists

TV

  • /tv/id
  • /tv/latest
  • /tv/id/similar
  • /tv/top_rated
  • /tv/popular

People

  • /person/id

Discover

  • /discover/movie
  • /discover/tv
Release History

Release History

This version
History Node

0.5

History Node

0.4

History Node

0.3

History Node

0.2.2.1

History Node

0.2.2

History Node

0.2.1

History Node

0.2

History Node

0.1

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
tmdbv3api-0.5-py2.py3-none-any.whl (10.3 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Oct 21, 2017
tmdbv3api-0.5.tar.gz (7.0 kB) Copy SHA256 Checksum SHA256 Source Oct 21, 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