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
| Name | Type | Default | Description |
|---|---|---|---|
api_key | str | TVDB API key. | |
token | Optional[str] | None | Bearer token from previous session (if already connected). |
Attributes
| Name | Type | Description |
|---|---|---|
token | Optional[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
| Name | Type | Default | Description |
|---|---|---|---|
series_id | str | Series ID. | |
language | str | 'eng' | Language code. |
Returns
Dict[str, str]Dictionary mapping episode codes to titles.
get_detailsasync
async def get_details( item_id: str, content_type: ContentType, **kwargs,) -> Dict[str, Any]:Get item details from TVDB.
Parameters
| Name | Type | Description |
|---|---|---|
item_id | str | Item ID on TVDB. |
content_type | ContentType | Content type (TV_SERIES or MOVIE). |
**kwargs | Additional arguments including 'language'. |
Returns
Dict[str, Any]Dictionary with item details.
Raises
ValueErrorIf content_type is not supported.
get_movie_detailsasync
async def get_movie_details( movie_id: str, language: str = 'eng',) -> Dict[str, Any]:Get movie details from TVDB.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
movie_id | str | TVDB movie ID. | |
language | str | 'eng' | Language code. |
Returns
Dict[str, Any]Dictionary with movie details.
get_related_itemsasync
async def get_related_items( item_id: str, content_type: ContentType, **kwargs,) -> List[Dict[str, Any]]:Get related items (episodes for series).
Parameters
| Name | Type | Description |
|---|---|---|
item_id | str | TVDB series ID. |
content_type | ContentType | Content type (only TV_SERIES supported). |
**kwargs | Additional arguments including 'season_number'. |
Returns
List[Dict[str, Any]]List of episode dictionaries for TV_SERIES, empty list otherwise.
get_series_detailsasync
async def get_series_details( series_id: str, language: str = 'eng',) -> Dict[str, Any]:Get series details from TVDB.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
series_id | str | TVDB series ID. | |
language | str | 'eng' | Language code (e.g., 'eng', 'fra'). |
Returns
Dict[str, Any]Dictionary with series details including seasons.
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
| Name | Type | Default | Description |
|---|---|---|---|
series_id | str | TVDB series ID. | |
season_number | int | Season number to fetch. | |
language | str | 'eng' | Language code. |
Returns
List[Dict[str, Any]]List of episode dictionaries in standardized format.
searchasync
async def search( query: str, content_type: ContentType, **kwargs,) -> Dict[str, Any]:Search on TVDB.
Parameters
| Name | Type | Description |
|---|---|---|
query | str | Search term |
content_type | ContentType | Content type |
**kwargs | Additional arguments (language, year, etc.) |
Returns
Dict[str, Any]Search results in standardized format
search_moviesasync
async def search_movies( query: str, language: str = 'eng', **kwargs,) -> Dict[str, Any]:Search for movies on TVDB.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
query | str | Movie name | |
language | str | 'eng' | Language code |
Returns
Dict[str, Any]Search results
search_seriesasync
async def search_series( query: str, language: str = 'eng', **kwargs,) -> Dict[str, Any]:Search for TV series on TVDB.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
query | str | Series name | |
language | str | 'eng' | Language code (e.g., "eng", "fra") |
Returns
Dict[str, Any]Search results
Attributes
| Name | Value |
|---|---|
logger | logging.getLogger(__name__) |