TheTVDB Series & Episode Guide Scraper

Scrapes episode guide data from TheTVDB — the canonical episode metadata source powering Kodi, Plex, Sonarr, and most PVR software. You give it a list of series slugs; it returns a flat dataset with one row per episode, fully populated.

No API key required. No account needed.

What It Returns

Each row represents one episode. The schema is flat and consistent.

Field	Type	Description
series_slug	string	The series slug from the URL (e.g. game-of-thrones)
series_name	string	Series display name
tvdb_id	integer	TheTVDB numeric series ID
network	string	Broadcasting network or streaming service
status	string	Continuing or Ended
first_aired	string	ISO 8601 date the first episode aired
season_number	integer	Season number
episode_number	integer	Episode number within the season
episode_code	string	Standard code — S01E01, S02E03, etc.
episode_title	string	Episode title
episode_aired	string	ISO 8601 date this episode aired
episode_runtime	integer	Runtime in minutes
episode_overview	string	English synopsis
guest_stars	string	Comma-separated guest star names
directors	string	Comma-separated director names
writers	string	Comma-separated writer names

How to Use It

Find the slug in the TheTVDB URL. For https://www.thetvdb.com/series/game-of-thrones, the slug is game-of-thrones. Paste it (or several of them) into the Series Slugs field.

Input Parameters

Parameter	Type	Default	Description
seriesSlugs	array	—	One or more TheTVDB series slugs. Required.
maxItems	integer	10	Maximum episode records to return across all series.

Example Input

{
  "seriesSlugs": ["breaking-bad", "the-wire", "sopranos"],
  "maxItems": 200
}

Example Output Record

{
  "series_slug": "breaking-bad",
  "series_name": "Breaking Bad",
  "tvdb_id": 81189,
  "network": "AMC",
  "status": "Ended",
  "first_aired": "2008-01-20",
  "season_number": 1,
  "episode_number": 1,
  "episode_code": "S01E01",
  "episode_title": "Pilot",
  "episode_aired": "2008-01-20",
  "episode_runtime": 58,
  "episode_overview": "Walter White, a struggling high school chemistry teacher, is diagnosed with inoperable lung cancer and turns to manufacturing methamphetamine to secure his family's financial future.",
  "guest_stars": "Max Arciniega, Aaron Hill, Raymond Cruz",
  "directors": "Vince Gilligan",
  "writers": "Vince Gilligan"
}

Use Cases

• Building episode-aware watchlist apps that need structured air date data
• Populating PVR/media server databases with episode metadata
• TV analytics — air date patterns, runtime trends, network comparisons across seasons
• Training or augmenting language models with structured TV knowledge
• Research: tracking writer and director credits across a series run

How It Works

Three-level crawl, all server-rendered HTML. No JavaScript execution required.

1. Series page — Fetches /series/<slug> to extract the TVDB ID, network, status, and first air date.
2. Episode list — Fetches /series/<slug>/allseasons/official to collect all episode codes, titles, and detail URLs.
3. Episode detail — Fetches each /series/<slug>/episodes/<id> page to extract air date, runtime, English overview, and the full cast/crew table.

Concurrency is kept moderate. TheTVDB is a community-maintained database.

Notes

• episode_overview is always the English translation. TheTVDB stores overviews in many languages; this actor selects English specifically.
• guest_stars, directors, and writers are comma-separated strings. Empty when not listed on the episode.
• The maxItems limit applies across all series combined. If you specify three slugs and maxItems: 30, you get approximately 10 episodes per series (order is non-deterministic within a run).
• The scraper follows aired order (/allseasons/official). DVD order and absolute order are not crawled.

---

Data sourced from TheTVDB — the community-driven television database powering Kodi, Plex, and Sonarr since 2007.