Skip to content

sok.apis.video.tvdb_api

TVDB API Implementation The TVDB (TheTVDB.com) is a community database for TV series.

Documentation: https://thetvdb.github.io/v4-api/

TVDBApi

class TVDBApi(api_key: str, token: Optional[str] = None)

Bases: BaseAPI

TVDB API v4 implementation.

TVDB focuses primarily on TV series and provides detailed community data for television shows.

Initialize TVDB API.

Parameters

NameTypeDefaultDescription
api_keystrTVDB API key.
tokenOptional[str]NoneBearer token from previous session (if already connected).
Source

Attributes

NameTypeDescription
tokenOptional[str]

Bearer token for authenticated requests.

supported_content_typesproperty

List[ContentType]

Return content types supported by TVDB.

supported_media_typesproperty

List[MediaType]

Return media types supported by TVDB.

get_all_episodesasync

async def get_all_episodes(
series_id: str,
language: str = 'eng',
) -> Dict[str, str]:

Get all episodes from all seasons.

Parameters

NameTypeDefaultDescription
series_idstrSeries ID.
languagestr'eng'Language code.

Returns

  • Dict[str, str]Dictionary mapping episode codes to titles.
Source

get_detailsasync

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

Get item details from TVDB.

Parameters

NameTypeDescription
item_idstrItem ID on TVDB.
content_typeContentTypeContent type (TV_SERIES or MOVIE).
**kwargsAdditional arguments including 'language'.

Returns

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

Raises

  • ValueErrorIf content_type is not supported.
Source

get_movie_detailsasync

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

Get movie details from TVDB.

Parameters

NameTypeDefaultDescription
movie_idstrTVDB movie ID.
languagestr'eng'Language code.

Returns

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

Get related items (episodes for series).

Parameters

NameTypeDescription
item_idstrTVDB series ID.
content_typeContentTypeContent type (only TV_SERIES supported).
**kwargsAdditional arguments including 'season_number'.

Returns

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

get_series_detailsasync

async def get_series_details(
series_id: str,
language: str = 'eng',
) -> Dict[str, Any]:

Get series details from TVDB.

Parameters

NameTypeDefaultDescription
series_idstrTVDB series ID.
languagestr'eng'Language code (e.g., 'eng', 'fra').

Returns

  • Dict[str, Any]Dictionary with series details including seasons.
Source

get_series_episodesasync

async def get_series_episodes(
series_id: str,
season_number: int,
language: str = 'eng',
) -> List[Dict[str, Any]]:

Get episodes for a season.

Parameters

NameTypeDefaultDescription
series_idstrTVDB series ID.
season_numberintSeason number to fetch.
languagestr'eng'Language code.

Returns

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

Search on TVDB.

Parameters

NameTypeDescription
querystrSearch term
content_typeContentTypeContent type
**kwargsAdditional arguments (language, year, etc.)

Returns

  • Dict[str, Any]Search results in standardized format
Source

search_moviesasync

async def search_movies(
query: str,
language: str = 'eng',
**kwargs,
) -> Dict[str, Any]:

Search for movies on TVDB.

Parameters

NameTypeDefaultDescription
querystrMovie name
languagestr'eng'Language code

Returns

  • Dict[str, Any]Search results
Source

search_seriesasync

async def search_series(
query: str,
language: str = 'eng',
**kwargs,
) -> Dict[str, Any]:

Search for TV series on TVDB.

Parameters

NameTypeDefaultDescription
querystrSeries name
languagestr'eng'Language code (e.g., "eng", "fra")

Returns

  • Dict[str, Any]Search results
Source

Attributes

NameValue
loggerlogging.getLogger(__name__)
Built with Kiln