TheTVDB Series & Episode Guide Scraper

Pricing

Rating

Developer

Actor stats

Categories

Share

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.

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

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.