Object API

class TMDbAPIs(apikey: str, session_id: str | None = None, v4_access_token: str | None = None, language=None, session: Session | None = None)[source]

Bases: object

Main Object Class

Parameters:

  • apikey (str) – TMDb V3 API Key.

  • session_id (Optional[str]) – TMDb V3 Session ID.

  • v4_access_token (Optional[str]) – TMDb V4 Access Token.

  • language (str) – Default TMDb language.

  • session (Optional[Session]) – Use you’re own Session object

Variables:

  • language (str) – TMDb Language.

  • include_language (str) – Comma-separated list of TMDb Languages to have included with images and videos.

  • account_id (int) – TMDb V3 Account ID.

  • session_id (str) – TMDb V3 Session ID.

  • v4_account_id (str) – TMDb V4 Account ID.

  • v4_access_token (str) – TMDb V4 Access Token.

authenticate(username: str, password: str)[source]

Use this to authenticate the TMDb V3 Session.

Parameters:

  • username (str) – TMDb Username.

  • password (str) – TMDb Password.

v4_access(access_token: str)[source]

Use this method to set up TMDb’s V4 API

To gain read access to TMDb V4’s API just provide you’re TMDb V4 Access Token either with this method or by using the v4_access_token Parameter of the TMDbAPIs constructor.

To gain write access to TMDb V4’s API

  1. Gain Read Access

  2. Authenticate the URL returned from v4_authenticate().

  3. Approve the authentication using v4_approved().

To get you’re TMDb V3 Write Access Token use TMDbAPIs.v4_access_token After it’s been approved.

Parameters:

access_token (str) – TMDb V4 Access Token

v4_authenticate()[source]

Use this method to get the authentication URL for write access to TMDb V4 API

v4_approved()[source]

Use this method once the URL from v4_authenticate() has been authenticated to gain write access to TMDb V4 API

account()[source]

Account Object with your account details.

Returns:

Account

Raises:

Authentication – When you haven’t authenticated a session yet.

created_lists(v3: bool = False)[source]

Paginated Object of all the lists created by an account. Will include private lists if you are the owner.

Parameters:

v3 (bool) – Force List V3 Usage

Returns:

CreatedLists

favorite_movies(sort_by: str | None = None, v3: bool = False)[source]

Paginated Object of movies you have marked as a favorite.

Parameters:

  • sort_by (Optional[str]) – How the results are sorted.

  • v3 (bool) – Force List V3 Usage

Sort Options

created_at.asc

created_at.desc

release_date.asc *

release_date.desc *

title.asc *

title.desc *

vote_average.asc *

vote_average.desc *

* V4 Lists Only

Returns:

FavoriteMovies

Raises:

Invalid – When sort_by is not a valid option.

favorite_tv_shows(sort_by: str | None = None, v3: bool = False)[source]

Paginated Object of TV shows you have marked as a favorite.

Parameters:

  • sort_by (Optional[str]) – How the results are sorted.

  • v3 (bool) – Force List V3 Usage

Sort Options

created_at.asc

created_at.desc

first_air_date.asc *

first_air_date.desc *

name.asc *

name.desc *

vote_average.asc *

vote_average.desc *

* V4 Lists Only

Returns:

FavoriteTVShows

Raises:

Invalid – When sort_by is not a valid option.

rated_movies(sort_by: str | None = None, v3: bool = False)[source]

Paginated Object of movies you have rated.

Parameters:

  • sort_by (Optional[str]) – How the results are sorted.

  • v3 (bool) – Force List V3 Usage

Sort Options

created_at.asc

created_at.desc

release_date.asc *

release_date.desc *

title.asc *

title.desc *

vote_average.asc *

vote_average.desc *

* V4 Lists Only

Returns:

RatedMovies

Raises:

Invalid – When sort_by is not a valid option.

rated_tv_shows(sort_by: str | None = None, v3: bool = False)[source]

Paginated Object of TV shows you have rated.

Parameters:

  • sort_by (Optional[str]) – How the results are sorted.

  • v3 (bool) – Force List V3 Usage

Sort Options

created_at.asc

created_at.desc

first_air_date.asc *

first_air_date.desc *

name.asc *

name.desc *

vote_average.asc *

vote_average.desc *

* V4 Lists Only

Returns:

RatedTVShows

Raises:

Invalid – When sort_by is not a valid option.

rated_episodes(sort_by: str | None = None)[source]

Paginated Object of TV episodes you have rated.

Parameters:

sort_by (Optional[str]) – How the results are sorted.

Sort Options

created_at.asc

created_at.desc
Returns:

RatedEpisodes

Raises:

Invalid – When sort_by is not a valid option.

movie_watchlist(sort_by: str | None = None, v3: bool = False)[source]

Paginated Object of movies you have added to your watchlist.

Parameters:

  • sort_by (Optional[str]) – How the results are sorted.

  • v3 (bool) – Force List V3 Usage

Sort Options

created_at.asc

created_at.desc

release_date.asc *

release_date.desc *

title.asc *

title.desc *

vote_average.asc *

vote_average.desc *

* V4 Lists Only

Returns:

MovieWatchlist

Raises:

Invalid – When sort_by is not a valid option.

tv_show_watchlist(sort_by: str | None = None, v3: bool = False)[source]

Paginated Object of TV shows you have added to your watchlist.

Parameters:

  • sort_by (Optional[str]) – How the results are sorted.

  • v3 (bool) – Force List V3 Usage

Sort Options

created_at.asc

created_at.desc

first_air_date.asc *

first_air_date.desc *

name.asc *

name.desc *

vote_average.asc *

vote_average.desc *

* V4 Lists Only

Returns:

TVShowWatchlist

Raises:

Invalid – When sort_by is not a valid option.

movie_recommendations(sort_by: str | None = None)[source]

Paginated Object of your personal movie recommendations. (V4 Lists Only)

Parameters:

sort_by (Optional[str]) – How the results are sorted.

Sort Options

created_at.asc

created_at.desc

release_date.asc

release_date.desc

title.asc

title.desc

vote_average.asc

vote_average.desc
Returns:

MovieRecommendations

Raises:

Invalid – When sort_by is not a valid option.

tv_show_recommendations(sort_by: str | None = None)[source]

Paginated Object of your personal TV show recommendations. (V4 Lists Only)

Parameters:

sort_by (Optional[str]) – How the results are sorted.

Sort Options

created_at.asc

created_at.desc

first_air_date.asc

first_air_date.desc

name.asc

name.desc

vote_average.asc

vote_average.desc
Returns:

TVShowRecommendations

Raises:

Invalid – When sort_by is not a valid option.

logout()[source]

End all V3 and V4 Authenticated Sessions

movie_certifications(reload: bool = False) → Dict[str, CountryCertifications][source]

Get an up to date list of the officially supported movie certifications on TMDB.

Parameters:

reload (bool) – Reload the cached movie certifications

Returns:

Dict[str, CountryCertifications]

tv_certifications(reload: bool = False) → Dict[str, CountryCertifications][source]

Get an up to date list of the officially supported TV show certifications on TMDB.

Parameters:

reload (bool) – Reload the cached tv certifications

Returns:

Dict[str, CountryCertifications]

movie_change_list(start_date: datetime | str | None = None, end_date: datetime | str | None = None) → List[Movie][source]

Get a list of Movie that have been changed in the past 24 hours.

You can query it for up to 14 days worth of changed Movies at a time with the start_date and end_date query parameters.

Parameters:

  • start_date (Optional[Union[datetime, str]]) – Filter the results with a start date. Format: YYYY-MM-DD

  • end_date (Optional[Union[datetime, str]]) – Filter the results with an end date. Format: YYYY-MM-DD

Returns:

List[Movie]

Raises:

Invalid – When start_date or end_date is in an incorrect format.

tv_change_list(start_date: datetime | str | None = None, end_date: datetime | str | None = None) → List[TVShow][source]

Get a list of TV that have been changed in the past 24 hours.

You can query it for up to 14 days worth of changed Shows at a time with the start_date and end_date query parameters.

Parameters:

  • start_date (Optional[Union[datetime, str]]) – Filter the results with a start date. Format: YYYY-MM-DD

  • end_date (Optional[Union[datetime, str]]) – Filter the results with an end date. Format: YYYY-MM-DD

Returns:

List[TVShow]

Raises:

Invalid – When start_date or end_date is in an incorrect format.

person_change_list(start_date: datetime | str | None = None, end_date: datetime | str | None = None) → List[Person][source]

Get a list of Person that have been changed in the past 24 hours.

You can query it for up to 14 days worth of changed People at a time with the start_date and end_date query parameters.

Parameters:

  • start_date (Optional[Union[datetime, str]]) – Filter the results with a start date. Format: YYYY-MM-DD

  • end_date (Optional[Union[datetime, str]]) – Filter the results with an end date. Format: YYYY-MM-DD

Returns:

List[Person]

Raises:

Invalid – When start_date or end_date is in an incorrect format.

collection(collection_id: int, load: bool = True, partial: bool | str | None = False) → Collection[source]

Gets the Collection for the given id.

Parameters:

  • collection_id (int) – Collection ID of the collection you want.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

Collection

Raises:

NotFound – When no collection is found for the given id.

company(company_id: int, load: bool = True, partial: bool | str | None = False) → Company[source]

Gets the Company for the given id.

Parameters:

  • company_id (int) – Company ID of the company you want.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

Company

Raises:

NotFound – When no company is found for the given id.

configuration(reload: bool = False) → Configuration[source]

Gets the TMDb Configuration.

Parameters:

reload (bool) – Reload the cached Configuration.

Returns:

Configuration

credit(credit_id: str, load: bool = True) → Credit[source]

Gets the Credit for the given id.

Parameters:

  • credit_id (str) – Credit ID of the credit you want.

  • load (bool) – Load the data on creation.

Returns:

Credit

Raises:

NotFound – When no credit is found for the given id.

discover_movies(**kwargs) → DiscoverMovies[source]

Discover movies by different types of data like average rating, number of votes, genres and certifications. You can get a valid list of certifications from the movie_certifications() method.

Discover also supports a nice list of sort options. See below for all of the available options.

Please note, when using certification certification.lte you must also specify certification_country. These two parameters work together in order to filter the results. You can only filter results with the countries added to movie_certifications().

If you specify the region parameter, the regional release date will be used instead of the primary release date. The date returned will be the first date based on your query (ie. if a with_release_type is specified). It’s important to note the order of the release types that are used. Specifying “2|3” would return the limited theatrical release date as opposed to “3|2” which would return the theatrical date.

Also note that a number of filters support being comma (,) or pipe (|) separated. Comma’s are treated like an AND and query while pipe’s are an OR.

. cannot be included directly in the function parameters so the parameters must be provided as a kwargs dictionary.

Parameters:

  • language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.

  • region (Optional[str]) – ISO-3166-1 code to filter release dates. Must be uppercase.

  • sort_by (Optional[str]) – Allowed Values: popularity.asc, popularity.desc, release_date.asc, release_date.desc, revenue.asc, revenue.desc, primary_release_date.asc, primary_release_date.desc, title.asc, title.desc, original_title.asc, original_title.desc, vote_average.asc, vote_average.desc, vote_count.asc, vote_count.desc

  • certification_country (Optional[str]) – Used in conjunction with the certification filter, use this to specify a country with a valid certification.

  • certification (Optional[str]) – Filter results with a valid certification from the certification_country field.

  • certification.lte (Optional[str]) – Filter and only include movies that have a certification that is less than or equal to the specified value.

  • certification.gte (Optional[str]) – Filter and only include movies that have a certification that is greater than or equal to the specified value.

  • include_adult (Optional[bool]) – A filter and include or exclude adult movies.

  • include_video (Optional[bool]) – A filter to include or exclude videos.

  • page (Optional[int]) – Specify the page of results to query.

  • primary_release_year (Optional[int) – A filter to limit the results to a specific primary release year.

  • primary_release_date.gte (Optional[str]) – Filter and only include movies that have a primary release date that is greater or equal to the specified value. Format: YYYY-MM-DD

  • primary_release_date.lte (Optional[str]) – Filter and only include movies that have a primary release date that is less than or equal to the specified value. Format: YYYY-MM-DD

  • release_date.gte (Optional[str]) – Filter and only include movies that have a release date (looking at all release dates) that is greater or equal to the specified value. Format: YYYY-MM-DD

  • release_date.lte (Optional[str]) – 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. Format: YYYY-MM-DD

  • with_release_type (Optional[int]) – 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.

  • year (Optional[int]) – A filter to limit the results to a specific year (looking at all release dates).

  • vote_count.gte (Optional[int]) – Filter and only include movies that have a vote count that is greater or equal to the specified value.

  • vote_count.lte (Optional[int]) – Filter and only include movies that have a vote count that is less than or equal to the specified value.

  • vote_average.gte (Optional[float]) – Filter and only include movies that have a rating that is greater or equal to the specified value.

  • vote_average.lte (Optional[float]) – Filter and only include movies that have a rating that is less than or equal to the specified value.

  • with_cast (Optional[str]) – A comma separated list of person ID’s. Only include movies that have one of the ID’s added as an actor.

  • with_crew (Optional[str]) – A comma separated list of person ID’s. Only include movies that have one of the ID’s added as a crew member.

  • with_people (Optional[str]) – 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.

  • with_companies (Optional[str]) – A comma separated list of production company ID’s. Only include movies that have one of the ID’s added as a production company.

  • without_companies (Optional[str]) – A comma separated list of production company ID’s. Exclude movies that have one of the ID’s added as a production company.

  • with_genres (Optional[str]) – Comma separated value of genre ids that you want to include in the results.

  • without_genres (Optional[str]) – Comma separated value of genre ids that you want to exclude from the results.

  • with_keywords (Optional[str]) – A comma separated list of keyword ID’s. Only includes movies that have one of the ID’s added as a keyword.

  • without_keywords (Optional[str]) – Exclude items with certain keywords. You can comma and pipe separate these values to create an ‘AND’ or ‘OR’ logic.

  • with_runtime.gte (Optional[int]) – Filter and only include movies that have a runtime that is greater or equal to a value.

  • with_runtime.lte (Optional[int]) – Filter and only include movies that have a runtime that is less than or equal to a value.

  • with_origin_country (Optional[str]) – Filter and only include movies that have the given origin country.

  • with_original_language (Optional[str]) – Specify an ISO 639-1 string to filter results by their original language value.

  • with_title_translation (Optional[str]) – Specify a Primary Translation string to filter results by their title translation value.

  • with_overview_translation (Optional[str]) – Specify a Primary Translation string to filter results by their overview translation value.

  • with_watch_providers (Optional[str]) – A comma or pipe separated list of watch provider ID’s. Combine this filter with watch_region in order to filter your results by a specific watch provider in a specific region.

  • without_watch_providers (Optional[str]) – A comma or pipe separated list of watch provider ID’s. Combine this filter with watch_region in order to filter your results by a specific watch provider in a specific region.

  • watch_region (Optional[str]) – An ISO 3166-1 code. Combine this filter with with_watch_providers and with_watch_monetization_types in order to filter your results by a specific watch provider in a specific region.

  • with_watch_monetization_types (Optional[str]) – In combination with watch_region, you can filter by monetization type. Allowed Values: flatrate, free, ads, rent, buy

Returns:

DiscoverMovies

Raises:

Invalid – When one of the attributes given is Invalid.

discover_tv_shows(**kwargs) → DiscoverTVShows[source]

Discover TV shows by different types of data like average rating, number of votes, genres, the network they aired on and air dates.

Discover also supports a nice list of sort options. See below for all of the available options.

Also note that a number of filters support being comma (,) or pipe (|) separated. Comma’s are treated like an AND and query while pipe’s are an OR.

. cannot be included directly in the function parameters so the parameters must be provided as a kwargs dictionary.

Parameters:

  • language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.

  • sort_by (Optional[str]) – Allowed Values: popularity.desc, popularity.asc, first_air_date.desc, first_air_date.asc, name.asc, name.desc, original_name.asc, original_name.desc, vote_average.desc, vote_average.asc, vote_count.desc, vote_count.asc

  • air_date.gte (Optional[str]) – Filter and only include TV shows that have an air date (by looking at all episodes) that is greater or equal to the specified value. Format: YYYY-MM-DD

  • air_date.lte (Optional[str]) – Filter and only include TV shows that have an air date (by looking at all episodes) that is less than or equal to the specified value. Format: YYYY-MM-DD

  • first_air_date.gte (Optional[str]) – Filter and only include TV shows that have an original air date that is greater or equal to the specified value. Can be used in conjunction with the include_null_first_air_dates filter if you want to include items with no air date. Format: YYYY-MM-DD

  • first_air_date.lte (Optional[str]) – Filter and only include TV shows that have an original air date that is less than or equal to the specified value. Can be used in conjunction with the include_null_first_air_dates filter if you want to include items with no air date. Format: YYYY-MM-DD

  • first_air_date_year (Optional[int]) – Filter and only include TV shows that have an original air date year that equal to the specified value. Can be used in conjunction with the include_null_first_air_dates filter if you want to include items with no air date.

  • include_adult (Optional[bool]) – A filter and include or exclude adult shows.

  • page (Optional[int]) – Specify the page of results to query.

  • timezone (Optional[str]) – Used in conjunction with the air_date.gte/air_date.lte filter to calculate the proper UTC offset.

  • vote_average.gte (Optional[float]) – Filter and only include TV shows that have a rating that is greater or equal to the specified value.

  • vote_average.lte (Optional[float]) – Filter and only include TV shows that have a rating that is less than or equal to the specified value.

  • vote_count.gte (Optional[int]) – Filter and only include TV shows that have a vote count that is greater or equal to the specified value.

  • vote_count.lte (Optional[int]) – Filter and only include TV shows that have a vote count that is less than or equal to the specified value.

  • with_genres (Optional[str]) – Comma separated value of genre ids that you want to include in the results.

  • with_networks (Optional[str]) – Comma separated value of network ids that you want to include in the results.

  • without_genres (Optional[str]) – Comma separated value of genre ids that you want to exclude from the results.

  • with_runtime.gte (Optional[int]) – Filter and only include TV shows with an episode runtime that is greater than or equal to a value.

  • with_runtime.lte (Optional[int]) – Filter and only include TV shows with an episode runtime that is less than or equal to a value.

  • with_status (Optional[str]) – Filter and only include TV shows that have the given status values. Allowed Values: 0, 1, 2, 3, 4, 5

  • with_type (Optional[str]) – Filter and only include TV shows that have the given type values. Allowed Values: 0, 1, 2, 3, 4, 5, 6

  • include_null_first_air_dates (Optional[bool]) – Use this filter to include TV shows that don’t have an air date while using any of the first_air_date filters.

  • with_original_language (Optional[str]) – Specify an ISO 639-1 string to filter results by their original language value.

  • without_keywords (Optional[str]) – Exclude items with certain keywords. You can comma and pipe separate these values to create an ‘AND’ or ‘OR’ logic.

  • screened_theatrically (Optional[bool]) – Filter results to include items that have been screened theatrically.

  • with_companies (Optional[str]) – A comma separated list of production company ID’s. Only include movies that have one of the ID’s added as a production company.

  • without_companies (Optional[str]) – 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_keywords (Optional[str]) – A comma separated list of keyword ID’s. Only includes TV shows that have one of the ID’s added as a keyword.

  • with_name_translation (Optional[str]) – Specify a Primary Translation string to filter results by their name translation value.

  • with_overview_translation (Optional[str]) – Specify a Primary Translation string to filter results by their overview translation value.

  • with_watch_providers (Optional[str]) – A comma or pipe separated list of watch provider ID’s. Combine this filter with watch_region in order to filter your results by a specific watch provider in a specific region.

  • without_watch_providers (Optional[str]) – A comma or pipe separated list of watch provider ID’s. Combine this filter with watch_region in order to filter your results by a specific watch provider in a specific region.

  • watch_region (Optional[str]) – An ISO 3166-1 code. Combine this filter with with_watch_providers in order to filter your results by a specific watch provider in a specific region.

  • with_watch_monetization_types (Optional[str]) – In combination with watch_region, you can filter by monetization type. Allowed Values: flatrate, free, ads, rent, buy

Returns:

DiscoverTVShows

Raises:

Invalid – When one of the attributes given is Invalid.

find_by_id(imdb_id: str | None = None, freebase_mid: str | None = None, freebase_id: str | None = None, tvdb_id: str | None = None, tvrage_id: str | None = None, facebook_id: str | None = None, twitter_id: str | None = None, instagram_id: str | None = None) → FindResults[source]

Gets the FindResults for the given external id.

Parameters:

  • imdb_id (str) – IMDb ID to find.

  • freebase_mid (str) – Freebase MID to find.

  • freebase_id (str) – Freebase ID to find.

  • tvdb_id (str) – TVDb ID to find.

  • tvrage_id (str) – TVRage ID to find.

  • facebook_id (str) – Facebook ID to find.

  • twitter_id (str) – Twitter ID to find.

  • instagram_id (str) – Instagram ID to find.

Returns:

FindResults

Raises:

  • NotFound – When no results are returned.

  • Invalid – When no external id is given.

movie_genres(reload: bool = False) → List[Genre][source]

Gets a list of all movie Genre.

Parameters:

reload (bool) – Reload the cached movie genres.

Returns:

List[Genre]

tv_genres(reload: bool = False) → List[Genre][source]

Gets a list of all TV show Genre.

Parameters:

reload (bool) – Reload the cached movie genres.

Returns:

List[Genre]

keyword(keyword_id: int, load: bool = True) → Keyword[source]

Gets the Keyword for the given id.

Parameters:

  • keyword_id (int) – Keyword ID of the keyword you want.

  • load (bool) – Load the data on creation.

Returns:

Keyword

Raises:

NotFound – When no keyword is found for the given id.

list(list_id: int, load: bool = True) → TMDbList[source]

Gets the TMDbList for the given id.

Parameters:

  • list_id (str) – Keyword ID of the list you want.

  • load (bool) – Load the data on creation.

Returns:

TMDbList

Raises:

NotFound – When no list is found for the given id.

create_list(name: str, iso_639_1: Language | str, description: str | None = '', public: bool = True, iso_3166_1: Country | str | None = None, load: bool = True) → TMDbList | int[source]

Creates a new List on TMDb and returns either a TMDbList Object or the List ID.

Parameters:

  • name (str) – Name of the List.

  • iso_639_1 (Union[Language, str]) – ISO 639-1 Language Code of the List or tmdbapis.objs.simple.Language Object.

  • description (Optional[str]) – Description of the List.

  • public (bool) – Determine if the list is a public list. (V4 Lists Only)

  • iso_3166_1 (Optional[Union[Country, str]]) – ISO 3166-1 Alpha-2 Country Code of the List or tmdbapis.objs.simple.Country Object. (V4 Lists Only)

  • load (bool) – Load the list to return after creating it or just return the created List ID.

Returns:

Union[TMDbList, int]

movie(movie_id: int, load: bool = True, partial: bool | str | None = False) → Movie[source]

Gets the Movie for the given id.

Parameters:

  • movie_id (str) – Movie ID of the movie you want.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

Movie

Raises:

NotFound – When no keyword is found for the given id.

latest_movie() → Movie[source]

Gets the latest Movie added on TMDb.

Returns:

Movie

now_playing_movies(region: Country | str | None = None) → NowPlayingMovies[source]

Paginated Object of Movies Now playing in theaters.

Parameters:

region (Optional[Union[Country, str]]) – ISO 3166-1 Alpha-2 Country Code or tmdbapis.objs.simple.Country Object to narrow the search to only look for theatrical release dates within the specified country.

Returns:

NowPlayingMovies

Raises:

Invalid – When the Country provided is not valid.

popular_movies(region: Country | str | None = None) → PopularMovies[source]

Paginated Object of Popular Movies on TMDb.

Parameters:

region (Optional[Union[Country, str]]) – ISO 3166-1 Alpha-2 Country Code or tmdbapis.objs.simple.Country Object to narrow the search to only look for theatrical release dates within the specified country.

Returns:

PopularMovies

Raises:

Invalid – When the Country provided is not valid.

top_rated_movies(region: Country | str | None = None) → TopRatedMovies[source]

Paginated Object of the Top Rated Movies on TMDb.

Parameters:

region (Optional[Union[Country, str]]) – ISO 3166-1 Alpha-2 Country Code or tmdbapis.objs.simple.Country Object to narrow the search to only look for theatrical release dates within the specified country.

Returns:

TopRatedMovies

Raises:

Invalid – When the Country provided is not valid.

upcoming_movies(region: Country | str | None = None) → UpcomingMovies[source]

Paginated Object of Upcoming Movies.

Parameters:

region (Optional[Union[Country, str]]) – ISO 3166-1 Alpha-2 Country Code or tmdbapis.objs.simple.Country Object to narrow the search to only look for theatrical release dates within the specified country.

Returns:

UpcomingMovies

Raises:

Invalid – When the Country provided is not valid.

network(network_id: int, load: bool = True, partial: bool | str | None = False) → Network[source]

Gets the Network for the given id.

Parameters:

  • network_id (int) – Network ID of the network you want.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

Network

Raises:

NotFound – When no network is found for the given id.

trending(media_type: str, time_window: str) → Trending[source]

Gets the Trending for the given id.

Parameters:

  • media_type (str) – Trending media type. Allowed Values: all, movie, tv, and person

  • time_window (str) – Trending list time window. Allowed Values: day and week

Returns:

Trending

Raises:

Invalid – When media_type or time_window is given an invalid option.

person(person_id: int, load: bool = True, partial: bool | str | None = False) → Person[source]

Gets the Person for the given id.

Parameters:

  • person_id (int) – Person ID of the person you want.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

Person

Raises:

NotFound – When no person is found for the given id.

latest_person() → Person[source]

Gets the latest Person added on TMDb.

Returns:

Person

popular_people() → PopularPeople[source]

Paginated Object of Popular People on TMDb.

Returns:

PopularPeople

review(review_id: str, load: bool = True) → Review[source]

Gets the Review for the given id.

Parameters:

  • review_id (str) – Review ID of the review you want.

  • load (bool) – Load the data on creation.

Returns:

Review

Raises:

NotFound – When no review is found for the given id.

Searches TMDb for companies.

Parameters:

query (str) – Query to search for.

Returns:

SearchCompanies

Raises:

NotFound – When no results are found for the search.

Searches TMDb for collections.

Parameters:

query (str) – Query to search for.

Returns:

SearchCollections

Raises:

NotFound – When no results are found for the search.

Searches TMDb for keywords.

Parameters:

query (str) – Query to search for.

Returns:

SearchKeywords

Raises:

NotFound – When no results are found for the search.

Searches TMDb for movies.

Parameters:

  • query (str) – Query to search for.

  • include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.

  • region (Optional[Union[Country, str]]) – Specify a ISO 3166-1 code or tmdbapis.objs.simple.Country Object to filter release dates. Must be uppercase.

  • year (Optional[int]) – Specify a year for the search.

  • primary_release_year (Optional[int]) – Specify a primary release year for the search.

Returns:

SearchMovies

Raises:

NotFound – When no results are found for the search.

Searches TMDb for movies, tv shows, and people.

Parameters:

  • query (str) – Query to search for.

  • include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.

  • region (Optional[Union[Country, str]]) – Specify a ISO 3166-1 code or tmdbapis.objs.simple.Country Object to filter release dates. Must be uppercase.

Returns:

SearchMulti

Raises:

NotFound – When no results are found for the search.

Searches TMDb for people.

Parameters:

  • query (str) – Query to search for.

  • include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.

  • region (Optional[Union[Country, str]]) – Specify a ISO 3166-1 code or tmdbapis.objs.simple.Country Object to filter release dates. Must be uppercase.

Returns:

SearchPeople

Raises:

NotFound – When no results are found for the search.

Searches TMDb for tv shows.

Parameters:

  • query (str) – Query to search for.

  • include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.

  • first_air_date_year (Optional[int]) – Specify a first air date year for the search.

Returns:

SearchTVShows

Raises:

NotFound – When no results are found for the search.

tv_show(tv_id: int, load: bool = True, partial: bool | str | None = False) → TVShow[source]

Gets the TVShow for the given id.

Parameters:

  • tv_id (int) – TV ID of the show you want.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

TVShow

Raises:

NotFound – When no keyword is found for the given id.

latest_tv() → TVShow[source]

Gets the latest TVShow added on TMDb.

Returns:

TVShow

tv_airing_today() → TVShowsAiringToday[source]

Paginated Object of TV Shows Airing Today.

Returns:

TVShowsAiringToday

tv_on_the_air() → TVShowsOnTheAir[source]

Paginated Object of TV Shows On the Air.

Returns:

TVShowsOnTheAir

popular_tv() → PopularTVShows[source]

Paginated Object of Popular TV Shows.

Returns:

PopularTVShows

top_rated_tv() → TopRatedTVShows[source]

Paginated Object of Top Rated TV Shows On.

Returns:

TVShowsOnTheAir

tv_season(tv_id: int, season_number: int, load: bool = True, partial: bool | str | None = False) → Season[source]

Gets the Movie for the given id.

Parameters:

  • tv_id (int) – TV ID of the show the contains the season you want.

  • season_number (int) – Season number to grab.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

Season

Raises:

NotFound – When no season is found for the given id.

tv_episode(tv_id: int, season_number: int, episode_number: int, load: bool = True, partial: bool | str | None = False) → Episode[source]

Gets the Episode for the given id.

Parameters:

  • tv_id (int) – TV ID of the show the contains the season you want.

  • season_number (int) – Season number to grab.

  • episode_number (int) – Episode number to grab.

  • load (bool) – Load the data on creation.

  • partial (Optional[Union[bool, str]]) – leave False for a full load otherwise specify the endpoints you want added.

Returns:

Episode

Raises:

NotFound – When no keyword is found for the given id.

episode_group(episode_group_id: str, load: bool = True) → EpisodeGroup[source]

Gets the EpisodeGroup for the given id.

Parameters:

  • episode_group_id (str) – Episode Group ID that you want.

  • load (bool) – Load the data on creation.

Returns:

EpisodeGroup

Raises:

NotFound – When no keyword is found for the given id.

provider_regions(reload: bool = False) → List[Country][source]

Gets a List of Country.

Parameters:

reload (bool) – Reload the cached data.

Returns:

List[Country]

movie_providers(watch_region: Country | str | None = None, reload: bool = False) → List[WatchProvider][source]

Gets a List of WatchProvider for movies.

Parameters:

  • watch_region (Optional[Union[Country, str]]) – Specify a ISO 3166-1 code or tmdbapis.objs.simple.Country Object to filter release dates. Must be uppercase.

  • reload (bool) – Reload the cached data.

Returns:

List[WatchProvider]

tv_providers(watch_region: Country | str | None = None, reload: bool = False) → List[WatchProvider][source]

Gets a List of WatchProvider for shows.

Parameters:

  • watch_region (Optional[Union[Country, str]]) – Specify a ISO 3166-1 code or tmdbapis.objs.simple.Country Object to filter release dates. Must be uppercase.

  • reload (bool) – Reload the cached data.

Returns:

List[Country]