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: object

Base 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: BaseAPI

Client 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: BaseAPI

Client 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: BaseAPI

Client 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: BaseAPI

Client 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: BaseAPI

Client 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: BaseAPI

Client 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: BaseAPI

Client 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
}