You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This Python3 module implements the v3 API for
TheMovieDb.org , allowing access to movie,
tvshow, cast information, as well as related artwork. More information can be
found at:
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 python3-tmdb3 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 python3-tmdb3
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 python3-tmdb3 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 propagated
through any subsequent queries made through those objects.
Locale settings are controlled through two functions
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 python3-tmdb3 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)>]
Discovering:
The discoverTv() and discoverMovie() methods accepts multiple kwargs,
which tells TMDB to filter the tvshows or movies depending on that keywords.
The search methods provided by the python3-tmdb3 module return list-like
structures that will automatically grab new pages as needed, as we do with
the search methods.
As a side note:
discoverTv(): returns a list-like structure of Series instances
discoverMovie(): returns a list-like structure of Movie instances
discoverTv kwargs:
sort_by:
vote_average.desc
vote_average.asc
first_air_date.desc
first_air_date.asc
popularity.desc
popularity.asc
first_air_date_year: A string in the format yyyy-mm-dd
with_genres: Comma separated value of genre ids that you want to include in
the results
with_networks: Comma separated value of network ids that you want to
include in the results
without_genres: Comma separated value of genre ids that you want to exclude
from the results
without_keywords: Exclude items with certain keywords. You can comma and
pipe separate these values to create an 'AND' or 'OR' logic
air_date_gte: Filter and only include TV shows that have a air date (by
looking at all episodes) that is greater or equal to the specified value
air_date_lte: Filter and only include TV shows that have a air date (by
looking at all episodes) that is less than or equal to the specified value
first_air_date_gte: Filter and only include TV shows that have a original
air date that is greater or equal to the specified value
first_air_date_lte: Filter and only include TV shows that have a original
air date that is less than or equal to the specified value
vote_average_gte: Filter and only include movies that have a rating that is
greater or equal to the specified value
vote_count_gte: Filter and only include movies that have a rating that is
less than or equal to the specified value
with_runtime_gte: Filter and only include TV shows with an episode runtime
that is greater than or equal to a value
with_runtime_lte: Filter and only include TV shows with an episode runtime
that is less than or equal to a value
discoverMovie kwargs:
region: Specify a ISO 3166-1 code to filter release dates. Must be uppercase.
sort_by:
popularity.asc
popularity.desc
release_date.asc
release_date.desc
revenue.asc
revenue.desc
primary_release_date.asc
primary_release_date.desc
original_title.asc
original_title.desc
vote_average.asc
vote_average.desc
vote_count.asc
vote_count.desc
include_adult: A filter and include or exclude adult movies. (true/false)
primary_release_year: A filter to limit the results to a specific primary
primary_release_date_gte: Filter and only include movies that have a
primary release date that is greater or equal to the specified value.
primary_release_date_lte: Filter and only include movies that have a
primary release date that is less than or equal to the specified value.
release_date_gte: Filter and only include movies that have a release date
(looking at all release dates) that is greater or equal to the specified
value.
release_date_lte: Filter and only include movies that have a release date
(looking at all release dates) that is less than or equal to the specified
value.
vote_count_gte: Filter and only include movies that have a vote count that
is greater or equal to the specified value.
vote_count_lte: Filter and only include movies that have a vote count that
is less than or equal to the specified value.
vote_average_gte: Filter and only include movies that have a rating that
is greater or equal to the specified value.
vote_average_lte: Filter and only include movies that have a rating that
is less than or equal to the specified value.
with_cast: A comma separated list of person ID's. Only include movies that
have one of the ID's added as an actor.
with_crew: A comma separated list of person ID's. Only include movies that
have one of the ID's added as a crew member.
with_companies: A comma separated list of production company ID's. Only
include movies that have one of the ID's added as a production company.
with_genres: Comma separated value of genre ids that you want to include
in the results.
with_keywords: A comma separated list of keyword ID's. Only include movies
that have one of the ID's added as a keyword.
with_people: A comma separated list of person ID's. Only include movies
that have one of the ID's added as a either a actor or a crew member.
year: A filter to limit the results to a specific year (looking at all
release dates).
without_genres: Comma separated value of genre ids that you want to
exclude from the results.
with_runtime_gte: Filter and only include movies that have a runtime that
is greater or equal to a value.
with_runtime_lte: Filter and only include movies that have a runtime that
is less than or equal to a value.
with_release_type: Specify a comma (AND) or pipe (OR) separated value to
filter release types by. These release types map to the same values found on
the movie release date method (minimum: 1, maximum: 6)
with_original_language: Specify an ISO 639-1 string to filter results by
their original language value.
without_keywords: Exclude items with certain keywords. You can comma and
pipe separate these values to create an 'AND' or 'OR' logic.
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 python3-tmdb3
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.
