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
genres	array	Series genres as listed on TheTVDB
original_country	string	Series original country
original_language	string	Series original language
season_number	integer	Season number
episode_number	integer	Episode number within the season
episode_code	string	Standard code — S01E01, S02E03, etc.
episode_id	integer	TheTVDB numeric episode ID
episode_url	string	TheTVDB episode page URL
episode_title	string	Episode title
episode_aired	string	ISO 8601 date this episode aired
episode_runtime	integer	Runtime in minutes
content_rating	string	Content rating shown for the episode (e.g. TV-MA), when listed
episode_overview	string	English synopsis
episode_image_url	string	Episode thumbnail image URL, when available
guest_stars	string	Comma-separated guest star names, null when none listed
directors	string	Comma-separated director names, null when none listed
writers	string	Comma-separated writer names, null when none listed

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	0	Maximum episode records to return across all series, shared fairly between the series you list. 0 returns every episode.

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 — series, season, episode — in one run.

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, or null when TheTVDB lists none for the episode.
• The maxItems limit applies across all series combined. If you specify three slugs and maxItems: 30, you get 10 episodes per series; when a series has fewer episodes than its share, the leftover goes to the others.
• The scraper follows aired order (/allseasons/official). DVD order and absolute order are not crawled. Specials (season 0) are not included.

---

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