API Module¶
Account API¶
- class api.account_api.AccountAPI[source]
Bases:
BaseAPI- get_rated_movies(session_id, query_params=None)[source]
Retrieve a paginated list of movies rated by the user.
- Parameters:
session_id – Optional path parameter (e.g., account ID).
query_params – Optional dict of query parameters. Defaults to page 1 if not specified.
- Returns:
Response object with paginated list of rated movies. Example
response.data:{ "page": 1, "results": [ {"id": 550, "title": "Fight Club", "vote_average": 8.4, "vote_count": 26280} ], "total_pages": 3, "total_results": 42 }
Base API¶
Base API Module¶
This module provides the foundation for all API interactions with the Movie Database.
- class api.base_api.APIResponse(data: dict, status_code: int, url: str, headers: Any, cookies: Any, encoding: str, elapsed_seconds: float = 0.0, reason: str = '', request: str = '', request_params: dict | None = None, request_payload: dict | None = None)[source]
Bases:
object- cookies: Any
- data: dict
- elapsed_seconds: float = 0.0
- encoding: str
- headers: Any
- reason: str = ''
- request: str = ''
- request_params: dict | None = None
- request_payload: dict | None = None
- status_code: int
- url: str
- class api.base_api.BaseAPI[source]
Bases:
objectBase API client providing common HTTP methods.
This class handles authentication, session management, and HTTP operations for interacting with the Movie Database API.
- Variables:
base_url – The base URL for API requests.
headers – Default headers including authentication.
session – Persistent requests session.
- delete(endpoint, data=None, params=None)[source]
Perform a DELETE request to the specified endpoint.
- Parameters:
endpoint (str) – API endpoint path.
data (dict, optional) – Optional data payload to send in the request body.
params (dict, optional) – Optional query parameters.
- Returns:
API response with data, status code, and metadata. Example return:
APIResponse( data={"success": True, "status_code": 13, "status_message": "The item/record was deleted successfully."}, status_code=200, url="https://api.themoviedb.org/3/movie/550/rating", elapsed_seconds=0.14, reason="OK", request="DELETE", request_params=None, request_payload=None, )
- Return type:
APIResponse
- get(endpoint, params=None)[source]
Perform a GET request to the specified endpoint.
- Parameters:
endpoint (str) – API endpoint path.
params (dict, optional) – Optional query parameters.
- Returns:
API response with data, status code, and metadata. Example return:
APIResponse( data={"page": 1, "results": [{"id": 550, "title": "Fight Club"}]}, status_code=200, url="https://api.themoviedb.org/3/movie/popular?page=1", elapsed_seconds=0.12, reason="OK", request="GET", request_params={"page": 1}, request_payload=None, )
- Return type:
APIResponse
- post(endpoint, json=None, params=None)[source]
Perform a POST request to the specified endpoint.
- Parameters:
endpoint (str) – API endpoint path.
json (dict, optional) – JSON payload to send in the request body.
params (dict, optional) – Optional query parameters.
- Returns:
API response with data, status code, and metadata. Example return:
APIResponse( data={"success": True, "status_code": 1, "status_message": "Success."}, status_code=201, url="https://api.themoviedb.org/3/movie/550/rating", elapsed_seconds=0.15, reason="Created", request="POST", request_params=None, request_payload={"value": 8.5}, )
- Return type:
APIResponse
- put(endpoint, data=None)[source]
Perform a PUT request to the specified endpoint.
- Parameters:
endpoint (str) – API endpoint path.
data (dict, optional) – Optional JSON payload to send in the request body.
- Returns:
API response with data, status code, and metadata. Example return:
APIResponse( data={"success": True, "status_code": 12, "status_message": "The item/record was updated successfully."}, status_code=201, url="https://api.themoviedb.org/4/list/123", elapsed_seconds=0.20, reason="Created", request="PUT", request_params=None, request_payload={"description": "Updated description"}, )
- Return type:
APIResponse
Discover API¶
Discover API client for The Movie Database (TMDB) endpoints.
This module provides a high-level interface for interacting with discover-related TMDB API endpoints. It extends BaseAPI to inherit authentication, request handling, and response parsing functionality.
- Usage:
api = DiscoverAPI() response = api.discover_movies({‘with_genres’: ‘28’}) logger.info(response.data[‘total_results’])
- class api.discover_api.DiscoverAPI[source]
Bases:
BaseAPIClient for TMDB Discover API endpoints.
Provides methods for discovering movies by filtering and sorting across a wide range of attributes (genres, release dates, ratings, language, etc.). All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for discover endpoints.
- Example:
api = DiscoverAPI() results = api.discover_movies({‘with_genres’: ‘28’, ‘sort_by’: ‘popularity.desc’})
- discover_movies(query_params=None)[source]
Discover movies by filter and sort criteria.
Supported query parameters include: sort_by, include_adult, include_video, language, page, region, year, primary_release_year, with_genres, with_original_language, vote_average.gte and vote_count.gte (among others documented by TMDB).
- Parameters:
query_params – Optional dict of query parameters. Defaults to page 1 if not specified.
- Returns:
Response object with paginated list of matching movies. Example
response.data:{ "page": 1, "results": [ {"id": 27205, "title": "Inception", "original_language": "en", "genre_ids": [28, 878, 12], "vote_average": 8.4, "release_date": "2010-07-15"} ], "total_pages": 500, "total_results": 10000 }
Lists API¶
- class api.lists_api.ListsAPI[source]
Bases:
BaseAPIClient for TMDB Lists API endpoints.
Provides methods for creating, updating, deleting lists, and managing list items. All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for list endpoints.
- Example:
api = ListsAPI() new_list = api.create_list(name=”My Favorite Movies”, description=”A list of my favorite movies”, language=”en”)
- update_list(list_id, payload)[source]
Update an existing list’s metadata details.
- Parameters:
list_id – TMDB list ID to update.
payload – Dict containing fields to update (e.g., name, description).
- Returns:
Response object with updated list details. Example
response.data:{ "status_message": "The item/record was updated successfully.", "success": true, "status_code": 12 }
Movies API¶
Movies API client for The Movie Database (TMDB) endpoints.
This module provides a high-level interface for interacting with movie-related TMDB API endpoints. It extends BaseAPI to inherit authentication, request handling, and response parsing functionality.
- Usage:
api = MoviesAPI() response = api.get_movie_details(550) # Get Fight Club details logger.info(response.data[‘title’])
- class api.movies_api.MoviesAPI[source]
Bases:
BaseAPIClient for TMDB Movies API endpoints.
Provides methods for retrieving movie details, popular movies, top-rated movies, and alternative titles. All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for movie endpoints.
- Example:
api = MoviesAPI() movie = api.get_movie_details(550) popular = api.get_popular_movies({‘page’: 2})
- add_rating(movie_id, rating, query_params=None)[source]
Add a user rating for a specific movie.
- Parameters:
movie_id – TMDB movie ID.
rating – User rating value (0.5 to 10.0).
query_params – Optional dict of query parameters, such as session_id for authentication.
- Returns:
Response object with status of the rating submission. Example
response.data:{"success": true, "status_code": 1, "status_message": "Success."}
- delete_rating(movie_id, query_params=None)[source]
Delete a user rating for a specific movie.
- Parameters:
movie_id – TMDB movie ID.
query_params – Optional dict of query parameters, such as session_id for authentication.
- Returns:
Response object with status of the rating deletion. Example
response.data:{"success": true, "status_code": 13, "status_message": "The item/record was deleted successfully."}
- get_alt_title(movie_id)[source]
Retrieve alternative titles for a specific movie.
Returns localized and regional title variations for the movie.
- Parameters:
movie_id – TMDB movie ID.
- Returns:
Response object with list of alternative titles including country codes and title strings. Example
response.data:{ "id": 550, "titles": [ {"iso_3166_1": "BR", "title": "Clube da Luta", "type": ""}, {"iso_3166_1": "PL", "title": "Podziemny krąg", "type": ""} ] }
- get_movie_details(movie_id)[source]
Retrieve detailed information for a specific movie.
- Parameters:
movie_id – TMDB movie ID (e.g., 550 for Fight Club).
- Returns:
Response object with movie details including title, genres, production companies, and release info. Example
response.data:{ "adult": false, "id": 550, "title": "Fight Club", "original_title": "Fight Club", "original_language": "en", "release_date": "1999-10-15", "origin_country": ["US"], "genres": [{"id": 18, "name": "Drama"}], "production_companies": [ {"id": 508, "logo_path": "/7cxRWzi4LsVm4Utfpr1hfARNurT.png", "name": "Regency Enterprises", "origin_country": "US"} ] }
- get_movie_reviews(movie_id, query_params=None)[source]
Retrieve user reviews for a specific movie.
- Parameters:
movie_id – TMDB movie ID.
query_params – Optional dict of query parameters (e.g., page).
- Returns:
Response object with a paginated list of user reviews. Example
response.data:{ "id": 550, "page": 1, "results": [ {"id": "5b1c13b9c3a36848f2026384", "author": "Cat Ellington", "author_details": {"name": "Cat Ellington", "username": "CatEllington", "avatar_path": null, "rating": 8.0}, "content": "The film that launched...", "created_at": "2018-06-09T18:15:37.023Z", "updated_at": "2021-06-23T15:58:09.043Z", "url": "https://www.themoviedb.org/review/5b1c13b9c3a36848f2026384"} ], "total_pages": 1, "total_results": 8 }
- get_popular_movies(query_params=None)[source]
Retrieve a paginated list of currently popular movies.
- Parameters:
query_params – Optional dict of query parameters. Defaults to page 1 if not specified.
- Returns:
Response object with paginated list of popular movies. Example
response.data:{ "page": 1, "results": [ {"id": 550, "title": "Fight Club", "original_language": "en", "genre_ids": [18], "vote_average": 8.4, "vote_count": 26280, "release_date": "1999-10-15"} ], "total_pages": 500, "total_results": 10000 }
- get_top_rated(query_params=None)[source]
Retrieve a paginated list of top-rated movies.
- Parameters:
query_params – Optional dict of query parameters. Defaults to page 1 if not specified.
- Returns:
Response object with paginated list of top-rated movies. Example
response.data:{ "page": 1, "results": [ {"id": 278, "title": "The Shawshank Redemption", "original_language": "en", "vote_average": 8.7, "vote_count": 27000, "release_date": "1994-09-23"} ], "total_pages": 500, "total_results": 10000 }
Networks API¶
- class api.networks_api.NetworksAPI[source]
Bases:
BaseAPIClient for TMDB Networks API endpoints.
Provides methods for retrieving TV network details. All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for network endpoints.
- get_network_details(network_id)[source]
Retrieve detailed information for a specific TV network.
- Parameters:
network_id – TMDB network ID (e.g., 213 for Netflix).
- Returns:
Response object with network details including name, headquarters, homepage, logo path, and origin country. Example
response.data:{ "id": 213, "name": "Netflix", "headquarters": "Los Gatos, California, USA", "homepage": "https://www.netflix.com", "logo_path": "/wwemzKWzjKYJFfCeiB57q3r4Bcm.png", "origin_country": "" }
People API¶
- class api.people_api.PeopleAPI[source]
Bases:
BaseAPIClient for TMDB People API endpoints.
Provides methods for retrieving person details, popular people, and top-rated people. All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for people endpoints.
- get_person_details(person_id)[source]
Retrieve detailed information for a specific person.
- Parameters:
person_id – TMDB person ID (e.g., 287 for Brad Pitt).
- Returns:
Response object with person details including name, biography, known for movies, and birth info. Example
response.data:{ "adult": false, "id": 287, "name": "Brad Pitt", "gender": 2, "known_for_department": "Acting", "birthday": "1963-12-18", "place_of_birth": "Shawnee, Oklahoma, USA", "also_known_as": ["William Bradley Pitt"], "biography": "William Bradley Pitt is an American actor...", "imdb_id": "nm0000093", "profile_path": "/cckcYc2v0yh5tnZTdZk6bnywnBv.png" }
Reviews API¶
Reviews API client for The Movie Database (TMDB) endpoints.
This module provides a high-level interface for interacting with review-related TMDB API endpoints. It extends BaseAPI to inherit authentication, request handling, and response parsing functionality.
- Usage:
api = ReviewsAPI() response = api.get_review_details(“5b1c13b9c3a36848f2026384”) logger.info(response.data[‘author’])
- class api.reviews_api.ReviewsAPI[source]
Bases:
BaseAPIClient for TMDB Reviews API endpoints.
Provides methods for retrieving a single user review by its id. All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for review endpoints.
- Example:
api = ReviewsAPI() review = api.get_review_details(“5b1c13b9c3a36848f2026384”)
- get_review_details(review_id)[source]
Retrieve detailed information for a specific review.
- Parameters:
review_id – TMDB review ID (a 24-character hex string).
- Returns:
Response object with review details including author, content, media reference, and timestamps. Example
response.data:{ "id": "5b1c13b9c3a36848f2026384", "author": "Cat Ellington", "author_details": { "name": "Cat Ellington", "username": "CatEllington", "avatar_path": null, "rating": 8.0 }, "content": "The film that launched a thousand fight clubs...", "created_at": "2018-06-09T18:15:37.023Z", "iso_639_1": "en", "media_id": 550, "media_title": "Fight Club", "media_type": "movie", "updated_at": "2021-06-23T15:58:09.043Z", "url": "https://www.themoviedb.org/review/5b1c13b9c3a36848f2026384" }
Search API¶
Search API client for The Movie Database (TMDB) endpoints.
This module provides a high-level interface for interacting with search-related TMDB API endpoints. It extends BaseAPI to inherit authentication, request handling, and response parsing functionality.
- Usage:
api = SearchAPI() response = api.search_movies({‘query’: ‘Batman’}) logger.info(response.data[‘total_results’])
- class api.search_api.SearchAPI[source]
Bases:
BaseAPIClient for TMDB Search API endpoints.
Provides methods for searching movies by their original, translated and alternative titles. All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for search endpoints.
- Example:
api = SearchAPI() results = api.search_movies({‘query’: ‘Batman’, ‘year’: ‘1989’})
- search_movies(query_params=None)[source]
Search for movies by title with optional filters.
Supported query parameters: query, include_adult, language, primary_release_year, page, region, year.
- Parameters:
query_params – Optional dict of query parameters. Defaults to page 1 if not specified.
- Returns:
Response object with paginated list of matching movies. Example
response.data:{ "page": 1, "results": [ {"id": 268, "title": "Batman", "original_language": "en", "release_date": "1989-06-23", "vote_average": 7.2} ], "total_pages": 5, "total_results": 92 }
Trending API¶
Trending API client for The Movie Database (TMDB) endpoints.
This module provides a high-level interface for interacting with trending-related TMDB API endpoints. It extends BaseAPI to inherit authentication, request handling, and response parsing functionality.
- Usage:
api = TrendingAPI() response = api.get_trending_movies(‘day’) logger.info(response.data[‘total_results’])
- class api.trending_api.TrendingAPI[source]
Bases:
BaseAPIClient for TMDB Trending API endpoints.
Provides methods for retrieving the movies trending over a given time window. All methods return a response object containing status code, headers, and parsed data.
- Attributes:
_sub_path (str): Base path segment for trending endpoints.
- Example:
api = TrendingAPI() trending = api.get_trending_movies(‘week’)
- get_trending_movies(time_window, query_params=None)[source]
Retrieve the movies trending over a given time window.
- Parameters:
time_window – Trending window, either
'day'or'week'.query_params – Optional dict of query parameters. Defaults to page 1 if not specified.
- Returns:
Response object with paginated list of trending movies. Example
response.data:{ "page": 1, "results": [ {"id": 1061474, "title": "Superman", "original_language": "en", "release_date": "2025-07-09", "vote_average": 7.5} ], "total_pages": 1000, "total_results": 20000 }