Raw API 3

class API3(apikey: str, session_id: str | None = None, api4: API4 | None = None, session: Session | None = None, validate: bool = True)[source]

Bases: object

Raw V3 API Class containing all TMDb API3 calls.

Parameters:

apikey (str) – TMDb V3 API Key.
session_id (Optional[str]) – TMDb V3 Session ID.
api4 (Optional[API4]) – tmdbapis.api4.API4 object.
session (Optional[Session]) – requests.Session object.
validate (bool) – Validate the TMDb V3 API Key on creation.

Variables:

apikey (str) – TMDb V3 API Key.
session_id (str) – TMDb V3 Session ID.
account_id (str) – TMDb V3 Account ID.
response (Response) – TMDb V3 most recent full requests.Response object.

account_get_details(session_id: str | None = None, append_to_response: str | None = None) → Dict[source]

Account Get Details

Get your account details.

Supports append_to_response. Read more about this here.

Parameters:

session_id (Optional[str]) – Session ID.
append_to_response (Optional[str]) – Append other requests to the response.

account_get_created_lists(session_id: str | None = None, account_id: str | None = None, language: str | None = None, page: int | None = None) → Dict[source]

Account Get Created Lists

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

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

Account Get Favorite Movies

Get the list of your favorite movies.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

Account Get Favorite TV Shows

Get the list of your favorite TV shows.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

account_mark_as_favorite(media_type: str, media_id: int, favorite: bool, session_id: str | None = None, account_id: str | None = None) → Dict[source]

Account Mark as Favorite

This method allows you to mark a movie or TV show as a favorite item.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
media_type (str) – Media Type. Allowed Values: movie and tv
media_id (int) – Media ID.
favorite (bool) – Mark or Remove as favorite.

Account Get Rated Movies

Get a list of all the movies you have rated.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

Account Get Rated TV Shows

Get a list of all the TV shows you have rated.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

Account Get Rated TV Episodes

Get a list of all the TV episodes you have rated.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

Account Get Movie Watchlist

Get a list of all the movies you have added to your watchlist.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

Account Get TV Show Watchlist

Get a list of all the TV shows you have added to your watchlist.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

account_add_to_watchlist(media_type: str, media_id: int, watchlist: bool, session_id: str | None = None, account_id: str | None = None) → Dict[source]

Account Add to Watchlist

Add a movie or TV show to your watchlist.

Parameters:

session_id (Optional[str]) – Session ID.
account_id (Optional[str]) – Account ID.
media_type (str) – Media Type. Allowed Values: movie and tv
media_id (int) – Media ID.
watchlist (bool) – Add or remove from your Watchlist.

authentication_create_guest_session() → Dict[source]

Authentication Create Guest Session

This method will let you create a new guest session. Guest sessions are a type of session that will let a user rate movies and TV shows but not require them to have a TMDB user account. More information about user authentication can be found here.

Please note, you should only generate a single guest session per user (or device) as you will be able to attach the ratings to a TMDB user account in the future. There is also IP limits in place so you should always make sure it’s the end user doing the guest session actions.

If a guest session is not used for the first time within 24 hours, it will be automatically deleted.

authentication_create_request_token() → Dict[source]

Authentication Create Request Token

Create a temporary request token that can be used to validate a TMDB user login. More details about how this works can be found here.

authentication_create_session(request_token: str) → Dict[source]

Authentication Create Session

You can use this method to create a fully valid session ID once a user has validated the request token. More information about how this works can be found here.

Parameters:: request_token (str) – Request Token.

authentication_create_session_with_login(username, password, request_token) → Dict[source]

Authentication Create Session With Login

This method allows an application to validate a request token by entering a username and password.

Not all applications have access to a web view so this can be used as a substitute.

Please note, the preferred method of validating a request token is to have a user authenticate the request via the TMDB website. You can read about that method here.

Parameters:

username (str) – TMDb Username.
password (str) – TMDb Password.
request_token (str) – Request Token.

authentication_create_session_from_v4(access_token: str) → Dict[source]

Authentication Create Session (from v4 access token)

Use this method to create a v3 session ID if you already have a valid v4 access token. The v4 token needs to be authenticated by the user. Your standard “read token” will not validate to create a session ID.

Parameters:: access_token (str) – V4 Approved Access Token.

authentication_delete_session(session_id: str | None = None) → Dict[source]

Authentication Delete Session

If you would like to delete (or “logout”) from a session, call this method with a valid session ID.

Parameters:: session_id (Optional[str]) – Session ID.

certifications_get_movie_certifications() → Dict[source]

Certifications Get Movie Certifications

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

certifications_get_tv_certifications() → Dict[source]

Certifications Get TV Certifications

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

changes_get_movie_change_list(start_date: str | None = None, end_date: str | None = None) → Dict[source]

Changes Get Movie Change List

Get a list of all of the movie ids that have been changed in the past 24 hours.

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

Parameters:

start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD

changes_get_tv_change_list(start_date: str | None = None, end_date: str | None = None) → Dict[source]

Changes Get TV Change List

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

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

Parameters:

start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD

changes_get_person_change_list(start_date: str | None = None, end_date: str | None = None) → Dict[source]

Changes Get Person Change List

Get a list of all of the person ids that have been changed in the past 24 hours.

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

Parameters:

start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD

collections_get_details(collection_id: int, language: str | None = None, append_to_response: str | None = None, include_image_language: str | None = None) → Dict[source]

Collections Get Details

Get collection details by id.

Supports append_to_response. Read more about this here.

Parameters:

collection_id (int) – Collection ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages. (Used with images append_to_response)

collections_get_images(collection_id: int, language: str | None = None, include_image_language: str | None = None) → Dict[source]

Collections Get Images

Get the images for a collection by id.

Parameters:

collection_id (int) – Collection ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages.

collections_get_translations(collection_id: int, language: str | None = None) → Dict[source]

Collections Get Translations

Get the list translations for a collection by id.

Parameters:

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

companies_get_details(company_id: int, language: str | None = None, append_to_response: str | None = None, page: int | None = None) → Dict[source]

Companies Get Details

Get a companies details by id.

Supports append_to_response. Read more about this here.

Parameters:

company_id (int) – Company ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
page (Optional[int]) – Specify which page to query. (Used with movies append_to_response)

companies_get_alternative_names(company_id: int) → Dict[source]

Companies Get Alternative Names

Get the alternative names of a company.

Parameters:: company_id (int) – Company ID.

companies_get_images(company_id: int) → Dict[source]

Companies Get Images

Get a companies logos by id.

There are two image formats that are supported for companies, PNG’s and SVG’s. You can see which type the original file is by looking at the file_type field. We prefer SVG’s as they are resolution independent and as such, the width and height are only there to reflect the original asset that was uploaded. An SVG can be scaled properly beyond those dimensions if you call them as a PNG.

For more information about how SVG’s and PNG’s can be used, take a read through this document.

Parameters:: company_id (int) – Company ID.

companies_get_movies(company_id: int, language: str | None = None, page: int | None = None) → Dict[source]

Companies Get Movies

Get a companies movies by id.

Parameters:

company_id (int) – Company ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

configuration_get_api_configuration(append_to_response: str | None = None) → Dict[source]

Configuration Get API3 Configuration

Get the system wide configuration information. Some elements of the API3 require some knowledge of this configuration data. The purpose of this is to try and keep the actual API3 responses as light as possible. It is recommended you cache this data within your application and check for updates every few days.

This method currently holds the data relevant to building image URLs as well as the change key map.

To build an image URL, you will need 3 pieces of data. The base_url, size and file_path. Simply combine them all and you will have a fully qualified URL. Here’s an example URL:

https://image.tmdb.org/t/p/w500/8uO0gUM8aNqYLs1OsTBQiXu0fEv.jpg

The configuration method also contains the list of change keys which can be useful if you are building an app that consumes data from the change feed.

Supports append_to_response. Read more about this here.

Parameters:: append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.

configuration_get_countries() → Dict[source]

Configuration Get Countries

Get the list of countries (ISO 3166-1 tags) used throughout TMDB.

configuration_get_jobs() → Dict[source]

Configuration Get Jobs

Get a list of the jobs and departments we use on TMDB.

configuration_get_languages() → Dict[source]

Configuration Get Languages

Get the list of languages (ISO 639-1 tags) used throughout TMDB.

configuration_get_primary_translations() → Dict[source]

Configuration Get Primary Translations

Get a list of the officially supported translations on TMDB.

While it’s technically possible to add a translation in any one of the languages we have added to TMDB (we don’t restrict content), the ones listed in this method are the ones we also support for localizing the website with which means they are what we refer to as the “primary” translations.

These are all specified as IETF tags to identify the languages we use on TMDB. There is one exception which is image languages. They are currently only designated by a ISO-639-1 tag. This is a planned upgrade for the future.

We’re always open to adding more if you think one should be added. You can ask about getting a new primary translation added by posting on the forums.

One more thing to mention, these are the translations that map to our website translation project. You can view and contribute to that project here

configuration_get_timezones() → Dict[source]

Configuration Get Timezones

Get the list of timezones used throughout TMDB.

credits_get_details(credit_id: str) → Dict[source]

Credits Get Details

Get a movie or TV credit details by id.

Parameters:: credit_id (int) – Credit ID.

discover_movie_discover(**kwargs) → Dict[source]

Discover Movie Discover

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 certifications list 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 we have added to our certifications list.

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.

Some examples of what can be done with discover can be found here.

. 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, 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.
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_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.
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

discover_tv_discover(**kwargs) → Dict[source]

Discover TV Discover

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.

Some examples of what can be done with discover can be found here.

. 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: vote_average.desc, vote_average.asc, first_air_date.desc, first_air_date.asc, popularity.desc, popularity.asc
air_date.gte (Optional[str]) – 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. Format: YYYY-MM-DD
air_date.lte (Optional[str]) – 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. Format: YYYY-MM-DD
first_air_date.gte (Optional[str]) – Filter and only include TV shows that have a 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 a 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 a 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.
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.
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.
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.
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

find_find_by_id(external_id: int | str, external_source: str, language: str | None = None) → Dict[source]

FindResults FindResults by ID

The find method makes it easy to search for objects in our database by an external id.

This method will search all objects (movies, TV shows and people) and return the results in a single response.

The supported external sources for each object are as follows.

Media Databases
	Movies	TV Shows	TV Seasons	TV Episodes	People
IMDb ID	✓	✓	✗	✓	✓
TVDB ID	✗	✓	✓	✓	✗
Freebase MID*	✗	✓	✓	✓	✓
Freebase ID*	✗	✓	✓	✓	✓
TVRage ID*	✗	✓	✓	✓	✓

Social IDs
	Movies	TV Shows	TV Seasons	TV Episodes	People
Facebook	✓	✓	✗	✗	✓
Instagram	✓	✓	✗	✗	✓
Twitter	✓	✓	✗	✗	✓

* Defunct or no longer available as a service.

Parameters:

external_id (Union[int, str]) – External ID.
external_source (str) – External Source. Allowed Values: imdb_id, freebase_mid, freebase_id, tvdb_id, tvrage_id, facebook_id, twitter_id, instagram_id
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.

genres_get_movie_list(language: str | None = None) → Dict[source]

Genres Get Movie List

Get the list of official genres for movies.

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

genres_get_tv_list(language: str | None = None) → Dict[source]

Genres Get TV List

Get the list of official genres for TV shows.

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

guest_sessions_get_rated_movies(guest_session_id: str, language: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Guest Sessions Get Rated Movies

Get the rated movies for a guest session.

Parameters:

guest_session_id (str) – Guest Session ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

guest_sessions_get_rated_tv_shows(guest_session_id: str, language: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Guest Sessions Get Rated TV Shows

Get the rated TV shows for a guest session.

Parameters:

guest_session_id (str) – Guest Session ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

guest_sessions_get_rated_tv_episodes(guest_session_id: str, language: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Guest Sessions Get Rated TV Episodes

Get the rated TV episodes for a guest session.

Parameters:

guest_session_id (str) – Guest Session ID.
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]) – Sort the results. Allowed Values: created_at.asc and created_at.desc
page (Optional[int]) – Specify which page to query.

keywords_get_details(keyword_id: int, language: str | None = None, append_to_response: str | None = None, include_adult: bool | None = None) → Dict[source]

Keywords Get Details

Get keyword details by id.

Supports append_to_response. Read more about this here.

Parameters:

keyword_id (int) – Keyword ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results. (Used with movies append_to_response)

keywords_get_movies(keyword_id: int, language: str | None = None, include_adult: bool | None = None) → Dict[source]

Keywords Get Movies

Get the movies that belong to a keyword.

Parameters:

keyword_id (int) – Keyword ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.

lists_get_details(list_id: int, language: str | None = None, page: str | None = None) → Dict[source]

Lists Get Details

Get the details of a list.

Parameters:

list_id (int) – List ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

lists_check_item_status(list_id: int, movie_id: int) → Dict[source]

Lists Check Item Status

You can use this method to check if a movie has already been added to the list.

Parameters:

list_id (int) – List ID.
movie_id (int) – Movie ID to check list for.

lists_create_list(session_id: str | None = None, name: str | None = '', description: str | None = '', language: str | None = '') → Dict[source]

Lists Create List

Create a list.

Parameters:

session_id (Optional[str]) – Session ID.
name (Optional[str]) – List Name.
description (Optional[str]) – List Description.
language (Optional[str]) – Set the ISO-639-1 variant for your list.

lists_add_movie(list_id: int, movie_id: int, session_id: str | None = None) → Dict[source]

Lists Add Movie

Add a movie to a list.

Parameters:

list_id (int) – List ID.
movie_id (int) – Movie ID to check list for.
session_id (Optional[str]) – Session ID.

lists_remove_movie(list_id: int, movie_id: int, session_id: str | None = None) → Dict[source]

Lists Remove Movie

Remove a movie from a list.

Parameters:

list_id (int) – List ID.
movie_id (int) – Movie ID to check list for.
session_id (Optional[str]) – Session ID.

lists_clear_list(list_id: int, confirm: bool, session_id: str | None = None) → Dict[source]

Lists Clear List

Clear all of the items from a list.

Parameters:

list_id (int) – List ID.
confirm (bool) – Confirm you want to clear the list.
session_id (Optional[str]) – Session ID.

lists_delete_list(list_id: int, session_id: str | None = None) → Dict[source]

Lists Delete List

Delete a list.

Parameters:

list_id (int) – List ID.
session_id (Optional[str]) – Session ID.

Movies Get Details

Get the primary information about a movie.

Supports append_to_response. Read more about this here.

Parameters:

movie_id (int) – Movie ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
session_id (Optional[str]) – Session ID. (Used with account_states append_to_response)
guest_session_id (Optional[str]) – Guest Session ID. (Used with account_states append_to_response)
country (Optional[str]) – ISO-3166-1 value to display alternative titles. (Used with alternative_titles append_to_response)
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD (Used with changes append_to_response)
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD (Used with changes append_to_response)
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages. (Used with images append_to_response)
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages. (Used with videos append_to_response)
page (Optional[int]) – Specify which page to query. (Used with lists append_to_response)

movies_get_account_states(movie_id: int, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

Movies Get Account States

Grab the following account states for a session:

Movie rating
If it belongs to your watchlist
If it belongs to your favourite list

Parameters:

movie_id (int) – Movie ID.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

movies_get_alternative_titles(movie_id: int, country: str | None = None) → Dict[source]

Movies Get Alternative Titles

Get all of the alternative titles for a movie.

Parameters:

movie_id (int) – Movie ID.
country (Optional[str]) – Session ID.

movies_get_changes(movie_id: int, start_date: str | None = None, end_date: str | None = None, page: int | None = None) → Dict[source]

Movies Get Changes

Get the changes for a movie. By default only the last 24 hours are returned.

You can query up to 14 days in a single query by using the start_date and end_date query parameters.

Parameters:

movie_id (int) – Movie ID.
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD
page (Optional[int]) – Specify which page to query.

movies_get_credits(movie_id: int, language: str | None = None) → Dict[source]

Movies Get Credits

Get the cast and crew for a movie.

Parameters:

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

movies_get_external_ids(movie_id: int) → Dict[source]

Movies Get External IDs

Get the external ids for a movie. We currently support the following external sources.

Media Databases	Social IDs
IMDb ID	Facebook
	Instagram
	Twitter

Parameters:: movie_id (int) – Movie ID.

movies_get_images(movie_id: int, language: str | None = None, include_image_language: str | None = None) → Dict[source]

Movies Get Images

Get the images that belong to a movie.

Querying images with a language parameter will filter the results. If you want to include a fallback language (especially useful for backdrops) you can use the include_image_language parameter. This should be a comma separated value like so: include_image_language=en,null.

Parameters:

movie_id (int) – Movie ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages.

movies_get_keywords(movie_id: int) → Dict[source]

Movies Get Keywords

Get the keywords that have been added to a movie.

Parameters:: movie_id (int) – Movie ID.

movies_get_lists(movie_id: int, language: str | None = None, page: int | None = None) → Dict[source]

Movies Get Lists

Get a list of lists that this movie belongs to.

Parameters:

movie_id (int) – Movie ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

movies_get_recommendations(movie_id: int, language: str | None = None, page: int | None = None) → Dict[source]

Movies Get Recommendations

Get a list of recommended movies for a movie.

Parameters:

movie_id (int) – Movie ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

movies_get_release_dates(movie_id: int) → Dict[source]

Movies Get Release Dates

Get the release date along with the certification for a movie.

Release dates support different types:

Premiere

Theatrical (limited)

Theatrical

Digital

Physical

TV

Parameters:: movie_id (int) – Movie ID.

movies_get_reviews(movie_id: int, language: str | None = None, page: int | None = None) → Dict[source]

Movies Get Reviews

Get the user reviews for a movie.

Parameters:

movie_id (int) – Movie ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

movies_get_similar_movies(movie_id: int, language: str | None = None, page: int | None = None) → Dict[source]

Movies Get Similar Movies

Get a list of similar movies. This is not the same as the “Recommendation” system you see on the website.

These items are assembled by looking at keywords and genres.

Parameters:

movie_id (int) – Movie ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

movies_get_translations(movie_id: int) → Dict[source]

Movies Get Translations

Get a list of translations that have been created for a movie.

Parameters:: movie_id (int) – Movie ID.

movies_get_videos(movie_id: int, language: str | None = None, include_video_language: str | None = None) → Dict[source]

Movies Get Videos

Get the videos that have been added to a movie.

Querying videos with a language parameter will filter the results. If you want to include a fallback language you can use the include_video_language parameter. This should be a comma separated value like so: include_video_language=en,null.

Parameters:

movie_id (int) – Movie ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages.

movies_get_watch_providers(movie_id: int) → Dict[source]

Movies Get Watch Providers

Powered by our partnership with JustWatch, you can query this method to get a list of the availabilities per country by provider.

This is not going to return full deep links, but rather, it’s just enough information to display what’s available where.

You can link to the provided TMDB URL to help support TMDB and provide the actual deep links to the content.

Please note: In order to use this data you must attribute the source of the data as JustWatch. If we find any usage not complying with these terms we will revoke access to the API.

Parameters:: movie_id (int) – Movie ID.

movies_rate_movie(movie_id: int, value: float, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

Movies Rate Movie

Rate a movie.

Parameters:

movie_id (int) – Movie ID.
value (float) – Rating for the Movie.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

movies_delete_rating(movie_id: int, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

Movies Delete Rating

Remove your rating for a movie.

Parameters:

movie_id (int) – Movie ID.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

movies_get_latest(language: str | None = None) → Dict[source]

Movies Get Latest

Get the most newly created movie. This is a live response and will continuously change.

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

movies_get_now_playing(language: str | None = None, page: str | None = None, region: str | None = None) → Dict[source]

Movies Get Now Playing

Get a list of movies in theatres. This is a release type query that looks for all movies that have a release type of 2 or 3 within the specified date range.

You can optionally specify a region parameter which will narrow the search to only look for theatrical release dates within the specified country.

Parameters:

language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
region (Optional[str]) – ISO-3166-1 value to filter the search to only look for now playing dates within the specified country.

movies_get_popular(language: str | None = None, page: str | None = None, region: str | None = None) → Dict[source]

Movies Get Popular

Get a list of the current popular movies on TMDB. This list updates daily.

Parameters:

language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
region (Optional[str]) – ISO-3166-1 value to filter the search to only look for popular release dates within the specified country.

movies_get_top_rated(language: str | None = None, page: str | None = None, region: str | None = None) → Dict[source]

Movies Get Top Rated

Get the top rated movies on TMDB.

Parameters:

language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
region (Optional[str]) – ISO-3166-1 value to filter the search to only look for top rated release dates within the specified country.

movies_get_upcoming(language: str | None = None, page: str | None = None, region: str | None = None) → Dict[source]

Movies Get Upcoming

Get a list of upcoming movies in theatres. This is a release type query that looks for all movies that have a release type of 2 or 3 within the specified date range.

You can optionally specify a region parameter which will narrow the search to only look for theatrical release dates within the specified country.

Parameters:

language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
region (Optional[str]) – ISO-3166-1 value to filter the search to only look for upcoming release dates within the specified country.

networks_get_details(network_id: int, append_to_response: str | None = None) → Dict[source]

Networks Get Details

Get the details of a network.

Supports append_to_response. Read more about this here.

Parameters:

network_id (int) – Network ID.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.

networks_get_alternative_names(network_id: int) → Dict[source]

Networks Get Alternative Names

Get the alternative names of a network.

Parameters:: network_id (int) – Network ID.

networks_get_images(network_id: int) → Dict[source]

Networks Get Images

Get the TV network logos by id.

There are two image formats that are supported for networks, PNG’s and SVG’s. You can see which type the original file is by looking at the file_type field. We prefer SVG’s as they are resolution independent and as such, the width and height are only there to reflect the original asset that was uploaded. An SVG can be scaled properly beyond those dimensions if you call them as a PNG.

For more information about how SVG’s and PNG’s can be used, take a read through this document.

Parameters:: network_id (int) – Network ID.

trending_get_trending(media_type: str, time_window: str, page: str | None = None) → Dict[source]

Trending Get Trending

Get the daily or weekly trending items. The daily trending list tracks items over the period of a day while items have a 24 hour half life. The weekly list tracks items over a 7 day period, with a 7 day half life.

Valid Media Types
Media Type	Description
all	Include all movies, TV shows and people in the results as a global trending list.
movie	Show the trending movies in the results.
tv	Show the trending TV shows in the results.
person	Show the trending people in the results.

Valid Time Windows
Time Window	Description
day	View the trending list for the day.
week	View the trending list for the week.

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
page (Optional[int]) – Specify which page to query.

People Get Details

Get the primary person details by id.

Supports append_to_response. Read more about this here.

Parameters:

person_id (int) – Person ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD (Used with changes append_to_response)
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD (Used with changes append_to_response)
page (Optional[int]) – Specify which page to query. (Used with changes append_to_response)

people_get_changes(person_id: int, start_date: str | None = None, end_date: str | None = None, page: int | None = None) → Dict[source]

People Get Changes

Get the changes for a person. By default only the last 24 hours are returned.

You can query up to 14 days in a single query by using the start_date and end_date query parameters.

Parameters:

person_id (int) – Person ID.
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD
page (Optional[int]) – Specify which page to query.

people_get_movie_credits(person_id: int, language: str | None = None) → Dict[source]

People Get Movie Credits

Get the movie credits for a person.

Parameters:

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

people_get_tv_credits(person_id: int, language: str | None = None) → Dict[source]

People Get TV Credits

Get the TV show credits for a person.

Parameters:

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

people_get_combined_credits(person_id: int, language: str | None = None) → Dict[source]

People Get Combined Credits

Get the movie and TV credits together in a single response.

Parameters:

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

people_get_external_ids(person_id: int, language: str | None = None) → Dict[source]

People Get External IDs

Get the external ids for a person. We currently support the following external sources.

External Sources
IMDb ID
Facebook
Freebase MID*
Freebase ID*
Instagram
TVRage ID*
Twitter

* Defunct or no longer available as a service.

Parameters:

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

people_get_images(person_id: int) → Dict[source]

People Get Images

Get the images for a person.

Parameters:: person_id (int) – Person ID.

people_get_tagged_images(person_id: int, language: str | None = None, page: int | None = None) → Dict[source]

People Get Tagged Images

Get the images that this person has been tagged in.

Parameters:

person_id (int) – Person ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

people_get_translations(person_id: int, language: str | None = None) → Dict[source]

People Get Movie Credits

Get a list of translations that have been created for a person.

Parameters:

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

people_get_latest(language: str | None = None) → Dict[source]

People Get Latest

Get the most newly created person. This is a live response and will continuously change.

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

people_get_popular(language: str | None = None, page: str | None = None) → Dict[source]

People Get Popular

Get the list of popular people on TMDB. This list updates daily.

Parameters:

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

reviews_get_details(review_id: str) → Dict[source]

Reviews Get Details

Retrieve the details of a movie or TV show review.

Parameters:: review_id (str) – Review ID.

search_search_companies(query: str, page: int | None = None) → Dict[source]

Search Search Companies

Search for companies.

Parameters:

query (str) – Pass a text query to search. This value should be URI encoded.
page (Optional[int]) – Specify which page to query.

search_search_collections(query: str, language: str | None = None, page: int | None = None) → Dict[source]

Search Search Collections

Search for collections.

Parameters:

query (str) – Pass a text query to search. This value should be URI encoded.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

search_search_keywords(query: str, page: int | None = None) → Dict[source]

Search Search Keywords

Search for keywords.

Parameters:

query (str) – Pass a text query to search. This value should be URI encoded.
page (Optional[int]) – Specify which page to query.

Search Search Movies

Search for movies.

Parameters:

query (str) – Pass a text query to search. This value should be URI encoded.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.
region (Optional[str]) – Specify a ISO 3166-1 code 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.

search_multi_search(query: str, language: str | None = None, page: int | None = None, include_adult: bool | None = None, region: str | None = None) → Dict[source]

Search Multi Search

Search multiple models in a single request. Multi search currently supports searching for movies, tv shows and people in a single request.

Parameters:

query (str) – Pass a text query to search. This value should be URI encoded.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.
region (Optional[str]) – Specify a ISO 3166-1 code to filter release dates. Must be uppercase.

search_search_people(query: str, language: str | None = None, page: int | None = None, include_adult: bool | None = None, region: str | None = None) → Dict[source]

Search Search People

Search for people.

Parameters:

query (str) – Pass a text query to search. This value should be URI encoded.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
include_adult (Optional[bool]) – Choose whether to include adult (pornography) content in the results.
region (Optional[str]) – Specify a ISO 3166-1 code to filter release dates. Must be uppercase.

search_search_tv_shows(query: str, language: str | None = None, page: int | None = None, include_adult: bool | None = None, first_air_date_year: int | None = None) → Dict[source]

Search Search TV Shows

Search for TV show.

Parameters:

query (str) – Pass a text query to search. This value should be URI encoded.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.
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.

TV Get Details

Get the primary TV show details by id.

Supports append_to_response. Read more about this here.

Parameters:

tv_id (int) – TV show ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
session_id (Optional[str]) – Session ID. (Used with account_states append_to_response)
guest_session_id (Optional[str]) – Guest Session ID. (Used with account_states append_to_response)
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD (Used with changes append_to_response)
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD (Used with changes append_to_response)
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages. (Used with images append_to_response)
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages. (Used with videos append_to_response)
page (Optional[int]) – Specify which page to query. (Used with lists append_to_response)

tv_get_account_states(tv_id: int, language: str | None = None, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

TV Get Account States

Grab the following account states for a session:

TV rating
If it belongs to your watchlist
If it belongs to your favourite list

Parameters:

tv_id (int) – TV ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

tv_get_aggregate_credits(tv_id: int, language: str | None = None) → Dict[source]

TV Get Aggregate Credits

Get the aggregate credits (cast and crew) that have been added to a TV show.

This call differs from the main credits call in that it does not return the newest season but rather, is a view of all the entire cast & crew for all episodes belonging to a TV show.

Parameters:

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

tv_get_alternative_titles(tv_id: int) → Dict[source]

TV Get Alternative Titles

Returns all of the alternative titles for a TV show.

Parameters:: tv_id (int) – TV ID.

tv_get_changes(tv_id: int, start_date: str | None = None, end_date: str | None = None, page: int | None = None) → Dict[source]

TV Get Changes

Get the changes for a TV show. By default only the last 24 hours are returned.

You can query up to 14 days in a single query by using the start_date and end_date query parameters.

TV show changes are different than movie changes in that there are some edits on seasons and episodes that will create a change entry at the show level. These can be found under the season and episode keys. These keys will contain a series_id and episode_id. You can use the tv_seasons_get_changes() and tv_episodes_get_changes() methods to look these up individually.

Parameters:

tv_id (int) – TV ID.
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD
page (Optional[int]) – Specify which page to query.

tv_get_content_ratings(tv_id: int, language: str | None = None) → Dict[source]

TV Get Content Ratings

Get the list of content ratings (certifications) that have been added to a TV show.

Parameters:

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

tv_get_credits(tv_id: int, language: str | None = None) → Dict[source]

TV Get Credits

Get the credits (cast and crew) that have been added to a TV show.

Parameters:

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

tv_get_episode_groups(tv_id: int, language: str | None = None) → Dict[source]

TV Get Episode Groups

Get all of the episode groups that have been created for a TV show. With a group ID you can call the tv_episode_groups_get_details() method.

Parameters:

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

tv_get_external_ids(tv_id: int) → Dict[source]

TV Get External IDs

Get the external ids for a TV show. We currently support the following external sources.

Media Databases	Social IDs
IMDb ID	Facebook
TVDB ID	Instagram
Freebase MID*	Twitter
Freebase ID*
TVRage ID*

* Defunct or no longer available as a service.

Parameters:: tv_id (int) – TV ID.

tv_get_images(tv_id: int, language: str | None = None, include_image_language: str | None = None) → Dict[source]

TV Get Images

Get the images that belong to a TV show.

Querying images with a language parameter will filter the results. If you want to include a fallback language (especially useful for backdrops) you can use the include_image_language parameter. This should be a comma separated value like so: include_image_language=en,null.

Parameters:

tv_id (int) – TV ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages.

tv_get_keywords(tv_id: int) → Dict[source]

TV Get Keywords

Get the keywords that have been added to a TV show.

Parameters:: tv_id (int) – TV ID.

tv_get_recommendations(tv_id: int, language: str | None = None, page: int | None = None) → Dict[source]

TV Get Recommendations

Get the list of TV show recommendations for this item.

Parameters:

tv_id (int) – TV ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

tv_get_reviews(tv_id: int, language: str | None = None, page: int | None = None) → Dict[source]

TV Get Reviews

Get the reviews for a TV show.

Parameters:

tv_id (int) – TV ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

tv_get_screened_theatrically(tv_id: int) → Dict[source]

TV Get Screened Theatrically

Get a list of seasons or episodes that have been screened in a film festival or theatre.

Parameters:: tv_id (int) – TV ID.

tv_get_similar_tv_shows(tv_id: int, language: str | None = None, page: int | None = None) → Dict[source]

TV Get Similar TV Shows

Get a list of similar TV shows. These items are assembled by looking at keywords and genres.

Parameters:

tv_id (int) – TV ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
page (Optional[int]) – Specify which page to query.

tv_get_translations(tv_id: int) → Dict[source]

TV Get Translations

Get a list of the translations that exist for a TV show.

Parameters:: tv_id (int) – TV ID.

tv_get_videos(tv_id: int, language: str | None = None, include_video_language: str | None = None) → Dict[source]

TV Get Similar TV Shows

Get the videos that have been added to a TV show.

Querying videos with a language parameter will filter the results. If you want to include a fallback language you can use the include_video_language parameter. This should be a comma separated value like so: include_video_language=en,null.

Parameters:

tv_id (int) – TV ID.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages.

tv_get_watch_providers(tv_id: int) → Dict[source]

TV Get Watch Providers

Powered by our partnership with JustWatch, you can query this method to get a list of the availabilities per country by provider.

This is not going to return full deep links, but rather, it’s just enough information to display what’s available where.

You can link to the provided TMDB URL to help support TMDB and provide the actual deep links to the content.

Please note: In order to use this data you must attribute the source of the data as JustWatch. If we find any usage not complying with these terms we will revoke access to the API.

Parameters:: tv_id (int) – TV ID.

tv_rate_tv_show(tv_id: int, value: float, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

TV Rate TV Show

Rate a TV show.

Parameters:

tv_id (int) – TV ID.
value (float) – Rating for the TV show.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

tv_delete_rating(tv_id: int, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

TV Delete Rating

Remove your rating for a TV show.

Parameters:

tv_id (int) – TV ID.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

tv_get_latest(language: str | None = None) → Dict[source]

TV Get Latest

Get the most newly created TV show. This is a live response and will continuously change.

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

tv_get_tv_airing_today(language: str | None = None, page: int | None = None) → Dict[source]

TV Get TV Airing Today

Get a list of TV shows that are airing today. This query is purely day based as we do not currently support airing times. (Eastern Time UTC-05:00)

Parameters:

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

tv_get_tv_on_the_air(language: str | None = None, page: int | None = None) → Dict[source]

TV Get TV On The Air

Get a list of shows that are currently on the air.

This query looks for any TV show that has an episode with an air date in the next 7 days.

Parameters:

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

tv_get_popular(language: str | None = None, page: int | None = None) → Dict[source]

TV Get Popular

Get a list of the current popular TV shows on TMDB. This list updates daily.

Parameters:

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

tv_get_top_rated(language: str | None = None, page: int | None = None) → Dict[source]

TV Get Top Rated

Get a list of the top rated TV shows on TMDB.

Parameters:

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

tv_seasons_get_details(tv_id: int, season_number: int, language: str | None = None, append_to_response: str | None = None, session_id: str | None = None, guest_session_id: str | None = None, include_image_language: str | None = None, include_video_language: str | None = None) → Dict[source]

TV Seasons Get Details

Get the TV season details by id.`

Supports append_to_response. Read more about this here.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
session_id (Optional[str]) – Session ID. (Used with account_states append_to_response)
guest_session_id (Optional[str]) – Guest Session ID. (Used with account_states append_to_response)
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages. (Used with images append_to_response)
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages. (Used with videos append_to_response)

tv_seasons_get_account_states(tv_id: int, season_number: int, language: str | None = None, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

TV Seasons Get Account States

Returns all of the user ratings for the season’s episodes.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

tv_seasons_get_aggregate_credits(tv_id: int, season_number: int, language: str | None = None) → Dict[source]

TV Seasons Get Aggregate Credits

Get the aggregate credits for TV season.

This call differs from the main credits call in that it does not only return the season credits, but rather is a view of all the cast & crew for all of the episodes belonging to a season.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.

tv_seasons_get_changes(season_id: int, start_date: str | None = None, end_date: str | None = None, page: int | None = None) → Dict[source]

TV Seasons Get Changes

Get the changes for a TV season. By default only the last 24 hours are returned.

You can query up to 14 days in a single query by using the start_date and end_date query parameters.

Parameters:

season_id (int) – Season ID.
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD
page (Optional[int]) – Specify which page to query.

tv_seasons_get_credits(tv_id: int, season_number: int, language: str | None = None) → Dict[source]

TV Seasons Get Credits

Get the credits for TV season.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.

tv_seasons_get_external_ids(tv_id: int, season_number: int) → Dict[source]

TV Seasons Get Credits

Get the external ids for a TV season. We currently support the following external sources.

Media Databases
TVDB ID
Freebase MID*
Freebase ID*
TVRage ID*

* Defunct or no longer available as a service.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.

tv_seasons_get_images(tv_id: int, season_number: int, language: str | None = None, include_image_language: str | None = None) → Dict[source]

TV Seasons Get Images

Get the images that belong to a TV season.

Querying images with a language parameter will filter the results. If you want to include a fallback language (especially useful for backdrops) you can use the include_image_language parameter. This should be a comma separated value like so: include_image_language=en,null.

Parameters:

tv_id (int) – TV ID.
season_number (int) – Season Number of TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages.

tv_seasons_get_translations(tv_id: int, season_number: int) → Dict[source]

TV Seasons Get Translations

Get the translation data for a TV season.

Parameters:

tv_id (int) – TV ID.
season_number (int) – Season Number of TV show.

tv_seasons_get_videos(tv_id: int, season_number, language: str | None = None, include_video_language: str | None = None) → Dict[source]

TV Seasons Get Videos

Get the videos that have been added to a TV season.

Querying videos with a language parameter will filter the results. If you want to include a fallback language you can use the include_video_language parameter. This should be a comma separated value like so: include_video_language=en,null.

Parameters:

tv_id (int) – TV ID.
season_number (int) – Season Number of TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages.

tv_episodes_get_details(tv_id: int, season_number: int, episode_number: int, language: str | None = None, append_to_response: str | None = None, session_id: str | None = None, guest_session_id: str | None = None, include_image_language: str | None = None, include_video_language: str | None = None) → Dict[source]

TV Episodes Get Details

Get the TV episode details by id.

Supports append_to_response. Read more about this here.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
append_to_response (Optional[str]) – Comma-separated list of sub requests within the same namespace.
session_id (Optional[str]) – Session ID. (Used with account_states append_to_response)
guest_session_id (Optional[str]) – Guest Session ID. (Used with account_states append_to_response)
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages. (Used with images append_to_response)
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages. (Used with videos append_to_response)

tv_episodes_get_account_states(tv_id: int, season_number: int, episode_number: int, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

TV Episodes Get Account States

Get your rating for a episode.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

tv_episodes_get_changes(episode_id, start_date: str | None = None, end_date: str | None = None, page: int | None = None) → Dict[source]

TV Episodes Get Changes

Get the changes for a TV episode. By default only the last 24 hours are returned.

You can query up to 14 days in a single query by using the start_date and end_date query parameters.

Parameters:

episode_id (int) – Episode ID.
start_date (Optional[str]) – Filter the results with a start date. Format: YYYY-MM-DD
end_date (Optional[str]) – Filter the results with an end date. Format: YYYY-MM-DD
page (Optional[int]) – Specify which page to query.

tv_episodes_get_credits(tv_id: int, season_number: int, episode_number: int, language: str | None = None) → Dict[source]

TV Episodes Get Credits

Get the credits (cast, crew and guest stars) for a TV episode.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.

tv_episodes_get_external_ids(tv_id: int, season_number: int, episode_number: int) → Dict[source]

TV Episodes Get External IDs

Get the external ids for a TV episode. We currently support the following external sources.

External Sources
IMDb ID
TVDB ID
Freebase MID*
Freebase ID*
TVRage ID*

* Defunct or no longer available as a service.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.

tv_episodes_get_images(tv_id: int, season_number: int, episode_number: int, language: str | None = None, include_image_language: str | None = None) → Dict[source]

TV Episodes Get Images

Get the images that belong to a TV episode.

Querying images with a language parameter will filter the results. If you want to include a fallback language (especially useful for backdrops) you can use the include_image_language parameter. This should be a comma separated value like so: include_image_language=en,null.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_image_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional image languages.

tv_episodes_get_translations(tv_id: int, season_number: int, episode_number: int) → Dict[source]

TV Episodes Get Translations

Get the translation data for an episode.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.

tv_episodes_rate_tv_episode(tv_id: int, season_number: int, episode_number: int, value: float, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

TV Episodes Rate TV Episode

Rate a TV episode.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.
value (float) – Rating for the TV show.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

tv_episodes_delete_rating(tv_id: int, season_number: int, episode_number: int, session_id: str | None = None, guest_session_id: str | None = None) → Dict[source]

TV Episodes Delete Rating

Remove your rating for a TV episode.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.
session_id (Optional[str]) – Session ID.
guest_session_id (Optional[str]) – Guest Session ID.

tv_episodes_get_videos(tv_id: int, season_number: int, episode_number: int, language: str | None = None, include_video_language: str | None = None) → Dict[source]

TV Episodes Get Videos

Get the videos that have been added to a TV episode.

Querying videos with a language parameter will filter the results. If you want to include a fallback language you can use the include_video_language parameter. This should be a comma separated value like so: include_video_language=en,null.

Parameters:

tv_id (int) – TV show ID.
season_number (int) – Season Number of TV show.
episode_number (int) – Episode Number of the Season in the TV show.
language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
include_video_language (Optional[str]) – Comma-separated list of ISO-639-1 values or null to query for additional video languages. (Used with videos append_to_response)

tv_episode_groups_get_details(episode_group_id: str, language: str | None = None) → Dict[source]

TV Episode Groups Get Details

Get the details of a TV episode group. Groups support 7 different types which are enumerated as the following:

Original air date

Absolute

DVD

Digital

Story arc

Production

TV

Parameters:

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

watch_providers_get_available_regions(language: str | None = None) → Dict[source]

Watch Providers Get Available Regions

Returns a list of all of the countries we have watch provider (OTT/streaming) data for.

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

watch_providers_get_movie_providers(language: str | None = None, watch_region: str | None = None) → Dict[source]

Watch Providers Get Movie Providers

Returns a list of the watch provider (OTT/streaming) data we have available for movies. You can specify a watch_region param if you want to further filter the list by country.

Parameters:

language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
watch_region (Optional[str]) – Use the ISO-3166-1 code to filter the providers that are available in a particular country.

watch_providers_get_tv_providers(language: str | None = None, watch_region: str | None = None) → Dict[source]

Watch Providers Get TV Providers

Returns a list of the watch provider (OTT/streaming) data we have available for TV series. You can specify a watch_region param if you want to further filter the list by country.

Parameters:

language (Optional[str]) – ISO-639-1 or ISO-3166-1 value to display translated data for the fields that support it.
watch_region (Optional[str]) – Use the ISO-3166-1 code to filter the providers that are available in a particular country.

Raw API 4

class API4(access_token: str, session: Session | None = None, validate: bool = True)[source]

Bases: object

Raw V4 API Class containing all TMDb API4 calls.

Parameters:

access_token (str) – TMDb V4 Access Token.
session (Optional[Session]) – requests.Session object.
validate (bool) – Validate the TMDb V4 Access Token on creation.

Variables:

access_token (str) – TMDb V4 Access Token.
has_write_token (bool) – Does the provided TMDb V4 Access Token have write access.
account_id (str) – TMDb V4 Account ID.
response (Response) – TMDb V4 most recent full requests.Response object.

account_get_lists(account_id: str | None = None, page: int | None = None) → Dict[source]

Account Get Lists

Get all of the lists you’ve created.

Parameters:

account_id (Optional[str]) – Account ID.
page (Optional[int]) – Specify which page to query.

account_get_favorite_movies(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get Favorite Movies

Get the list of movies you have marked as a favorite.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: created_at.asc, created_at.desc, release_date.asc, release_date.desc, title.asc, title.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

account_get_favorite_tv_shows(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get Favorite TV Shows

Get the list of TV shows you have marked as a favorite.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: first_air_date.asc, first_air_date.desc, name.asc, name.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

account_get_movie_recommendations(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get Movie Recommendations

Get a list of your personal movie recommendations.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: created_at.asc, created_at.desc, release_date.asc, release_date.desc, title.asc, title.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

account_get_tv_show_recommendations(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get TV Show Recommendations

Get a list of your personal TV show recommendations.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: first_air_date.asc, first_air_date.desc, name.asc, name.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

account_get_movie_watchlist(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get Movie Watchlist

Get the list of movies you have added to your watchlist.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: created_at.asc, created_at.desc, release_date.asc, release_date.desc, title.asc, title.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

account_get_tv_show_watchlist(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get TV Show Watchlist

Get the list of TV shows you have added to your watchlist.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: first_air_date.asc, first_air_date.desc, name.asc, name.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

account_get_rated_movies(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get Rated Movies

Get the list of movies you have rated.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: created_at.asc, created_at.desc, release_date.asc, release_date.desc, title.asc, title.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

account_get_rated_tv_shows(account_id: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

Account Get Rated TV Shows

Get the list of TV shows you have rated.

Parameters:

account_id (Optional[str]) – Account ID.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: first_air_date.asc, first_air_date.desc, name.asc, name.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

auth_create_request_token(redirect_to: str | None = None) → Dict[source]

Auth Create Request Token

This method generates a new request token that you can ask a user to approve. This is the first step in getting permission from a user to read and write data on their behalf. You can read more about this system here.

Parameters:: redirect_to (Optional[str]) – Redirect URL or callback that will be executed once a request token has been approved on TMDb.

auth_create_access_token(request_token: str) → Dict[source]

Auth Create Access Token

This method will finish the user authentication flow and issue an official user access token. The request token in this request is sent along as part of the POST body. You should still use your standard API read access token for authenticating this request.

Parameters:: request_token (str) – Request Token

auth_delete_access_token(access_token: str) → Dict[source]

Auth Delete Access Token

This method gives your users the ability to log out of a session.

Parameters:: access_token (str) – Access Token

list_get_list(list_id: int, language: str | None = None, sort_by: str | None = None, page: str | None = None) → Dict[source]

List Get List

This method will retrieve a list by id.

Private lists can only be accessed by their owners and therefore require a valid user access token.

Parameters:

list_id (int) – List ID
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]) – Choose a sort option for the list of results. Allowed Values: original_order.asc, original_order.desc, release_date.asc, release_date.desc, title.asc, title.desc, vote_average.asc, vote_average.desc
page (Optional[int]) – Specify which page to query.

list_create_list(name: str, iso_639_1: str, description: str | None = None, public: bool | None = None, iso_3166_1: str | None = None) → Dict[source]

List Create List

This method will create a new list.

You will need to have valid user access token in order to create a new list.

Parameters:

name (str) – Set the name of your list.
iso_639_1 (str) – Set the ISO-639-1 variant for your list.
description (Optional[str]) – Set the description of your list.
public (Optional[bool]) – Toggle the public status of your list.
iso_3166_1 (Optional[int]) – Set the ISO-3166-1 variant for your list.

list_update_list(list_id: int, name: str | None = None, description: str | None = None, public: bool | None = None, sort_by: str | None = None) → Dict[source]

List Update List

This method will let you update the details of a list.

You must be the owner of the list and therefore have a valid user access token in order to edit it.

Parameters:

list_id (int) – List ID
name (Optional[str]) – Set the name of your list.
description (Optional[str]) – Set the description of your list.
public (Optional[bool]) – Toggle the public status of your list.
sort_by (Optional[str]) – Choose a sort option for the list of results. Allowed Values: original_order.asc, original_order.desc, vote_average.asc, vote_average.desc, primary_release_date.asc, primary_release_date.desc, title.asc, title.desc

list_clear_list(list_id: int) → Dict[source]

List Clear List

This method lets you clear all of the items from a list in a single request. This action cannot be reversed so use it with caution.

You must be the owner of the list and therefore have a valid user access token in order to clear a list.

Parameters:: list_id (int) – List ID

list_delete_list(list_id: int) → Dict[source]

List Clear List

This method will delete a list by id. This action is not reversible so take care when issuing it.

You must be the owner of the list and therefore have a valid user access token in order to delete it.

Parameters:: list_id (int) – List ID

list_add_items(list_id: int, items: List[Dict[str, str | int]]) → Dict[source]

List Add Items

This method will let you add items to a list. We support essentially an unlimited number of items to be posted at a time. Both movie and TV series are support.

The results of this query will return a results array. Each result includes a success field. If a result is false this will usually indicate that the item already exists on the list. It may also indicate that the item could not be found.

You must be the owner of the list and therefore have a valid user access token in order to add items to a list.

Parameters:

list_id (int) – List ID
items (List[Dict[str, Union[str, int]]]) – List of items to add. Each item is a dictionary with the format {“media_type”: str, “media_id”: int}. media_type can either be movie or tv.

list_update_items(list_id: int, items: List[Dict[str, str | int]]) → Dict[source]

List Update Items

This method will let you update an individual item on a list. Currently, only adding a comment is supported.

You must be the owner of the list and therefore have a valid user access token in order to edit items.

Parameters:

list_id (int) – List ID
items (List[Dict[str, Union[str, int]]]) – List of items to update. Each item is a dictionary with the format {“media_type”: str, “media_id”: int, “comment”: str}. media_type can either be movie or tv.

list_remove_items(list_id: int, items: List[Dict[str, str | int]]) → Dict[source]

List Remove Items

This method will let you remove items from a list. You can remove multiple items at a time.

You must be the owner of the list and therefore have a valid user access token in order to delete items from it.

Parameters:

list_id (int) – List ID
items (List[Dict[str, Union[str, int]]]) – List of items to remove. Each item is a dictionary with the format {“media_type”: str, “media_id”: int}. media_type can either be movie or tv.

list_check_item_status(list_id: int, media_id: int, media_type: str) → Dict[source]

List Check Item Status

This method lets you quickly check if the item is already added to the list.

You must be the owner of the list and therefore have a valid user access token in order to check an item status.

Parameters:

list_id (int) – List ID
media_id (int) – Media ID
media_type (str) – Set the kind of media object are you checking. Allowed Values: movie, tv