Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Python interface to TheMovieDB.org v3 API
Python
branch: master

Merge pull request #60 from gazpachoking/manifest

Add manifest to include license and readme in packages. fix #59
latest commit 07c849512d
@wagnerrp authored

README.md

PyTMDB3

This Python module implements the v3 API for TheMovieDb.org, allowing access to movie and cast information, as well as related artwork. More information can be found at:

http://help.themoviedb.org/kb/api/about-3

Initial Access

Access to the API requires a personal key. You can create one by signing up for an account on TheMovieDb.org, and generating one from your Account Details page. Once done, the PyTMDB3 module must be be given this key as follows:

>>> from tmdb3 import set_key
>>> set_key('your_api_key')

Caching Engine

In order to limit excessive usage against the online API server, the PyTMDB3 module supports caching of requests. Cached data is keyed off the request URL, and is currently stored for one hour. API requests are limited to thirty (30) within ten (10) seconds. Requests beyond this limit are blocking until they can be processed.

There are currently two engines available for use. The null engine merely discards all information, and is only intended for debugging use. The file engine is defualt, and will store to /tmp/pytmdb3.cache unless configured otherwise. The cache engine can be configured as follows.

>>> from tmdb3 import set_cache
>>> set_cache('null')
>>> set_cache(filename='/full/path/to/cache') # the 'file' engine is assumed
>>> set_cache(filename='tmdb3.cache')         # relative paths are put in /tmp
>>> set_cache(engine='file', filename='~/.tmdb3cache')

Locale Configuration

The previous v2 API supported language selection, but would fall through to the defaults for any fields that did not have language-specific values. The v3 API no longer performs this fall through, leaving it up to clients to optionally implement it on their own.

The PyTMDB3 module supports the use of locales in two separate manners. One can define a global locale that is automatically used if not specified otherwise, or a specific locale can be supplied directly to searches and data queries using the locale= keyword argument, which is then propogated through any subsequent queries made through those objects.

Locale settings are controlled through two functions

>>> from tmdb3 import get_locale, set_locale
>>> get_locale()
<Locale None_None>
>>> set_locale()
>>> get_locale()
<Locale en_US>
>>> set_locale('en', 'gb')
>>> get_locale()
<Locale en_GB>
>>> get_locale('fr', 'fr')
<Locale fr_FR>
  • set_locale() is used to set the global default locale. It optionally accepts language and country keyword arguments. If not supplied, it will attempt to pull such information from your environment. It also accepts a fallthrough keyword argument, which is used to control the language and country filter fall through. This is disabled by default, meaning if a language is set, it will only return information specific to that language.

  • get_locale() also accepts optional language and country keyword arguments, and can be used to generate locales to use directly, overriding the global configuration. If none is given, this instead returns the global configuration. Note that fall through behavior is applied module-wide, and individual locales cannot be used to change that behavior.

Authentication

This is not yet supported.

Searching

There are currently six search methods available for use: movies, people, studios, lists, collections, and series. Search results from TheMovieDb are sent iteratively, twenty results per page. The search methods provided by the PyTMDB3 module return list-like structures that will automatically grab new pages as needed.

>>> from tmdb3 import searchMovie
>>> res = searchMovie('A New Hope')
>>> res
<Search Results: A New Hope>
>>> len(res)
4
>>> res[0]
<Movie 'Star Wars: Episode IV - A New Hope' (1977)>

The movieSearch() method accepts an 'adult' keyword to allow adult content to be returned. By default, this is set to False and such content is filtered out. The people search method behaves similarly.

>>> from tmdb import searchPerson
>>> res = searchPerson('Hanks')
>>> res
<Search Results: Hanks>
>>> res[0]
<Person 'Tom Hanks'>

>>> from tmdb import searchStudio
>>> res = searchStudio('Sony Pictures')
>>> res
<Search Results: Sony Pictures>
>>> res[0]
<Studio 'Sony Pictures'>

The movieSearch() method accepts a year keyword, which tells TMDB to filter for movies of only that specific year. There is a helper method, movieSearchWithYear(), which will process the release year from movie names where the year is contained in parentheses, as in:

>>> from tmdb import searchMovieWithYear
>>> list(searchMovieWithYear('Star Wars (1977)'))
[<Movie 'Star Wars: Episode IV - A New Hope' (1977)>, <Movie 'The Making of 'Star Wars'' (1977)>]

Direct Queries

There are currently four data types that support direct access: Collections, Movies, Persons, and Studios. These each take a single integer ID as an argument. All data attributes are implemented as properties, and populated on-demand as used, rather than when the object is created.

>>> from tmdb3 import Collection, Movie, Person, Studio
>>> Collection(10)
<Collection 'Star Wars Collection'>
>>> Movie(11)
<Movie 'Star Wars: Episode IV - A New Hope' (1977)>
>>> Person(2)
<Person 'Mark Hamill'>
>>> Studio(1)
<Studio 'Lucasfilm'>

The Genre class cannot be called by id directly, however it does have a getAll classmethod, capable of returning all available genres for a specified language.

Image Behavior

TheMovieDb currently offers three types of artwork: backdrops, posters, and profiles. The three data queries above will each carry a default one of these and potentially a list of additionals to choose from. Each can be downloaded directly, or at one of several pre-scaled reduced resolutions. The PyTMDB3 module provides a list of available sizes, and will generate a URL to download a requested size. Invalid sizes return an error.

>>> from tmdb3 import Movie
>>> p = Movie(11).poster
>>> p
<Poster 'tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'>
>>> p.sizes()
[u'w92', u'w154', u'w185', u'w342', u'w500', u'original']
>>> p.geturl()
u'http://cf2.imgobject.com/t/p/original/tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'
>>> p.geturl('w342')
u'http://cf2.imgobject.com/t/p/w342/tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'
>>> p.geturl('w300')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "tmdb3/tmdb_api.py", line 101, in geturl
    raise TMDBImageSizeError
tmdb3.tmdb_exceptions.TMDBImageSizeError: None

Trailers

TheMovieDb offers access to trailers on Youtube and Apple, however their use is slightly different. Youtube trailers offer an individual file, while Apple trailers offer multiple sizes.

>>> from tmdb3 import Movie
>>> movie = Movie(27205)
>>> movie.youtube_trailers
[<YoutubeTrailer 'Trailer 1'>, <YoutubeTrailer 'Trailer 2'>]
>>> movie.youtube_trailers[0].geturl()
'http://www.youtube.com/watch?v=suIIHZqDR30'
>>> movie.apple_trailers
[<AppleTrailer 'Teaser'>, <AppleTrailer 'Trailer 1'>, <AppleTrailer 'Trailer 2'>]
>>> movie.apple_trailers[0].sizes()
[u'480p', u'720p', u'1080p']
>>> movie.apple_trailers[0].geturl()
u'http://pdl.warnerbros.com/wbmovies/inception/Inception_TRL1_1080.mov'
>>> movie.apple_trailers[0].geturl()
u'http://pdl.warnerbros.com/wbmovies/inception/Inception_TRL1_480.mov'

List of Available Data

Collection:

type name
integer id
string name
string overview
Backdrop backdrop
Poster poster
list(Movie) members
list(Backdrop) backdrops
list(Poster) posters

Movie:

type name notes
integer id
string title language specific
string originaltitle origin language
string tagline
string overview
integer runtime
integer budget
integer revenue
datetime releasedate
string homepage
string IMDB reference id 'ttXXXXXXX'
Backdrop backdrop
Poster poster
float popularity
float userrating
integer votes
boolean adult
Collection collection
list(Genre) genres
list(Studio) studios
list(Country) countries
list(Language) languages
list(AlternateTitle) alternate_title
list(Cast) cast sorted by billing
list(Crew) crew
list(Backdrop) backdrops
list(Poster) posters
list(Keyword) keywords
dict(Release) releases indexed by country
list(Translation) translations
list(Movie) similar
list(List) lists
list(Movie) getSimilar()
None setFavorite(bool) mark favorite status for current user
None setRating(int) rate movie by current user
None setWatchlist(bool) mark watchlist status for current user

Movie classmethod:

type name notes
Movie fromIMDB(imdbid) special constructor for use with IMDb codes
Movie latest() gets latest movie added to database
list(Movie) nowplaying() content currently in theater
list(Movie) mostpopular() based off themoviedb.org page view counts
list(Movie) toprated() based off themoviedb.org user ratings
list(Movie) upcoming() curated list, typically contains 100 movies
list(Movie) favorites() current user's favorite movies
list(Movie) ratedmovies() movies rated by current user
list(Movie) watchlist() movies marked to watch by current user

Series:

type name
integer id
string name
string original_name
string overview
string homepage
integer number_of_seasons
integer number_of_episodes
float popularity
float userrating
integer votes
datetime first_air_date
datetime last_air_date
bool inproduction
string status
Backdrop backdrop
Poster poster
string imdb_id
string freebase_id
string freebase_mid
string tvdb_id
string tvrage_id
list(Person) authors
list(datetime) episode_run_time
list(Genre) genres
list(string) languages
list(string) origin_countries
list(Network) networks
list(Season) seasons
list(Cast) cast
list(Crew) crew
list(Backdrop) backdrops
list(Poster) posters
list(Series) similar
list(Keyword) keywords

Season:

type name
integer id
string name
datetime air_date
string overview
integer series_id
integer season_number
Poster poster
string freebase_id
string freebase_mid
string tvdb_id
string tvrage_id
list(Poster) posters
list(Episode) episodes

Episode:

type name
integer id
integer series_id
integer season_number
integer episode_number
string name
string overview
float userrating
integer votes
datetime air_date
string production_code
Backdrop still
string freebase_id
string freebase_mid
string tvdb_id
string tvrage_id
list(Backdrop) stills
list(Cast) cast
list(Cast) guest_stars
list(Crew) crew

List:

type name notes
hex string id
string name
string author
string description
integer favorites number of users that have marked list
string language
integer count
Poster poster
list(Movie) members

Person:

type name
integer id
string name
string biography
datetime dayofbirth
datetime dayofdeath
string homepage
Profile profile
boolean adult
list(string) aliases
list(ReverseCast) roles
list(ReverseCrew) crew
list(Profile) profiles

Cast (derived from Person):

type name notes
string character
integer order as appears in credits

Crew (derived from Person):

type name
string job
string department

ReverseCast (derived from Movie):

type name
string character

ReverseCrew (derived from Movie):

type name
string job
string department

Image:

type name notes
string filename arbitrary alphanumeric code
float aspectratio not available for default images
integer height not available for default images
integer width not available for default images
integer language not available for default images
float userrating
integer votes
list(string) sizes()
string geturl(size='original')

Backdrop (derived from Image)
Poster (derived from Image)
Profile (derived from Image)
Logo (derived from Image)

AlternateTitle:

type name
string country
string title

Release:

type name
string certification
string country
datetime releasedate

Translation:

type name
string name
string englishname
string language

Genre:

type name
integer id
string name
list(Movie) movies

Genre classmethods:

type name notes
list(Genre) getAll(language) returns list of all genres

Studio:

type name
integer id
string name
string description
string headquarters
Logo logo
Studio parent
list(Movie) movies

Network:

type name
integer id
string name

Country:

type name
string code
string name

Language:

type name
string code
string name

Trailer:

type name
string name
string size
string source

YoutubeTrailer (derived from Trailer)

type name
string geturl()

AppleTrailer

type name notes
string name
dict(Trailer) sources indexed by size
list(string) sizes()
string geturl(size=None)
Something went wrong with that request. Please try again.