Skip to content

sok.apis.video.tmdb_api

TMDB API client implementation.

Provides access to The Movie Database (TMDB) API for searching and retrieving detailed metadata about movies and TV series.

TMDBApi

class TMDBApi(access_token: str, session_id: Optional[str] = None)

Bases: BaseAPI

TMDB API implementation using JWT Bearer token (v4) for API v3.

Initializes the TMDB API.

Parameters

NameTypeDefaultDescription
access_tokenstrThe TMDB v4 Read Access Token (Bearer JWT)
session_idOptional[str]NoneOptional Session ID for user actions
Source

Attributes

NameDescription
access_token

The TMDB v4 Read Access Token.

session_id

Optional session ID for user actions.

supported_content_typesproperty

List[ContentType]

Return content types supported by TMDB.

supported_media_typesproperty

List[MediaType]

Return media types supported by TMDB.

get_detailsasync

async def get_details(
item_id: str,
content_type: ContentType,
**kwargs,
) -> Dict[str, Any]:

Get details for a movie or series.

Parameters

NameTypeDescription
item_idstrTMDB ID of the item.
content_typeContentTypeType of content (MOVIE or TV_SERIES).
**kwargsAdditional parameters including 'language'.

Returns

  • Dict[str, Any]Dictionary with item metadata.

Raises

  • ValueErrorIf content_type is not supported.
Source

get_movie_detailsasync

async def get_movie_details(
movie_id: str,
language: str = 'en',
) -> Dict[str, Any]:

Get detailed movie information.

Parameters

NameTypeDefaultDescription
movie_idstrTMDB movie ID.
languagestr'en'Language code for results.

Returns

  • Dict[str, Any]Dictionary with movie metadata.
Source
async def get_related_items(
item_id: str,
content_type: ContentType,
**kwargs,
) -> List[Dict[str, Any]]:

Get related items (episodes for a series).

Parameters

NameTypeDescription
item_idstrTMDB ID of the series.
content_typeContentTypeContent type (only TV_SERIES supported).
**kwargsAdditional parameters including 'language', 'season_number'.

Returns

  • List[Dict[str, Any]]List of episode dictionaries for TV_SERIES, empty list otherwise.
Source

get_tv_detailsasync

async def get_tv_details(tv_id: str, language: str = 'en') -> Dict[str, Any]:

Get detailed TV series information.

Parameters

NameTypeDefaultDescription
tv_idstrTMDB series ID.
languagestr'en'Language code for results.

Returns

  • Dict[str, Any]Dictionary with series metadata.
Source

get_tv_episodesasync

async def get_tv_episodes(
tv_id: str,
season_number: int,
language: str = 'en',
) -> List[Dict[str, Any]]:

Get episodes for a season.

Parameters

NameTypeDefaultDescription
tv_idstrTMDB series ID.
season_numberintSeason number to fetch.
languagestr'en'Language code for results.

Returns

  • List[Dict[str, Any]]List of episode dictionaries.
Source
async def search(
query: str,
content_type: ContentType,
**kwargs,
) -> Dict[str, Any]:

Search for movies or TV series.

Parameters

NameTypeDescription
querystrSearch query string.
content_typeContentTypeType to search (MOVIE or TV_SERIES).
**kwargsAdditional parameters including 'language'.

Returns

  • Dict[str, Any]Dictionary with 'results' list of matches.

Raises

  • ValueErrorIf content_type is not supported.
Source

search_movieasync

async def search_movie(title: str, language: str = 'en') -> Dict[str, Any]:

Search for a movie on TMDB.

Parameters

NameTypeDefaultDescription
titlestrMovie title to search for.
languagestr'en'Language code for results.

Returns

  • Dict[str, Any]Dictionary with 'results' list of matching movies.
Source

search_tvasync

async def search_tv(title: str, language: str = 'en') -> Dict[str, Any]:

Search for a TV series on TMDB.

Parameters

NameTypeDefaultDescription
titlestrSeries title to search for.
languagestr'en'Language code for results.

Returns

  • Dict[str, Any]Dictionary with 'results' list of matching series.
Source
Built with Kiln