Tvdb

TheTVDB Lookup

Search and retrieve TV series, movie, episode, and people information from TheTVDB using the official tvdb_v4_official Python package (TVDB API v4).

Environment Variables

TVDB_API_KEY=your-api-key-here

Reference

• Code Snippets: scripts/
• Official Python package: tvdb_v4_official (GitHub)
• API docs: https://thetvdb.github.io/v4-api/

Available Scripts

| Script | Purpose | |--------|---------| | tvdb_client.py | Core client: wraps tvdb_v4_official with env-based auth | | search.py | Search TVDB by query (series, movies, people) | | get_series.py | Get TV series info by TVDB ID | | get_movie.py | Get movie info by TVDB ID | | get_episodes.py | List episodes for a series | | get_person.py | Get person info by TVDB ID |

How It Works

1. Authenticates using TVDB_API_KEY from .env via the tvdb_v4_official.TVDB client
2. The client obtains a bearer token automatically (valid for 1 month)
3. All methods return Python dicts parsed from TVDB API JSON responses

Search Parameters

| Parameter | Type | Description | |-----------|------|-------------| | query | String | Search term (series name, movie title, person) | | type | String | Filter: series, movie, person | | year | Integer | Filter by year | | limit | Integer | Max results to return |

Usage

Search for a Series or Movie

from tvdb_client import get_client

tvdb = get_client()
results = tvdb.search("Breaking Bad", type="series")
for r in results:
    print(f"{r['name']} ({r.get('year', 'N/A')}) - ID: {r.get('tvdb_id')}")

Get Series Details by ID

from tvdb_client import get_client

tvdb = get_client()
series = tvdb.get_series(81189)  # Breaking Bad
print(series["name"], series.get("year"))

Get Extended Series Info (with seasons, characters, etc.)

from tvdb_client import get_client

tvdb = get_client()
series = tvdb.get_series_extended(81189)
for season in series.get("seasons", []):
    print(f"Season {season['number']} ({season['type']['name']})")

List Episodes for a Series

from tvdb_client import get_client

tvdb = get_client()
info = tvdb.get_series_episodes(81189, season_type="default", page=0)
for ep in info["episodes"]:
    print(f"S{ep['seasonNumber']:02d}E{ep['number']:02d} - {ep['name']}")

Get Movie Details

from tvdb_client import get_client

tvdb = get_client()
movie = tvdb.get_movie(31)  # Avengers
print(movie["name"])

# Extended info with characters
movie_ext = tvdb.get_movie_extended(31)
for c in movie_ext.get("characters", []):
    print(f"  {c.get('name')} - {c.get('personName')}")

Get Person Info

from tvdb_client import get_client

tvdb = get_client()
person = tvdb.get_person_extended(253463)
print(person["name"])

Get Next Airing for a Series

from tvdb_client import get_client

tvdb = get_client()
next_aired = tvdb.get_series_nextAired(81189)
print(next_aired)

Key API Methods

| Method | Description | |--------|-------------| | search(query, **kwargs) | Search across series, movies, people | | get_series(id) | Basic series record | | get_series_extended(id) | Full series with seasons, characters, artwork | | get_series_episodes(id, season_type, page) | Paginated episode list | | get_series_nextAired(id) | Next airing episode | | get_series_artworks(id, lang) | Series artwork | | get_movie(id) | Basic movie record | | get_movie_extended(id) | Full movie with characters, artwork | | get_episode(id) | Basic episode record | | get_episode_extended(id) | Full episode details | | get_season(id) | Basic season record | | get_season_extended(id) | Full season with episodes | | get_person(id) | Basic person record | | get_person_extended(id) | Full person with roles | | get_all_genres() | List all genres |

CLI Usage

cd skills/tvdb/scripts
uv run python search.py "Breaking Bad"
uv run python search.py "Breaking Bad" --type series
uv run python search.py "Avengers" --type movie --year 2012
uv run python get_series.py 81189
uv run python get_series.py 81189 --extended
uv run python get_movie.py 31
uv run python get_movie.py 31 --extended
uv run python get_episodes.py 81189
uv run python get_episodes.py 81189 --season 1
uv run python get_person.py 253463

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hevangel
• Source: hevangel/media-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.