TVmaze TV Show & Episode Scraper

Extract comprehensive TV show data from TVmaze — ratings, episodes, cast, schedules, and more for 50,000+ shows worldwide. No API key or authentication required.

What it does

Scrapes the TVmaze public REST API to collect detailed TV show metadata across 5 modes: search, browse, episode lists, TV schedules, and cast/people data.

Input

Field	Type	Description	Default
mode	string	What to scrape (see modes below)	searchShows
query	string	Show title or keyword (mode=searchShows)	breaking bad
showId	integer	TVmaze show ID for episode mode	—
scheduleDate	string	Date for schedule in YYYY-MM-DD format	today
scheduleCountry	string	Country code for broadcast schedule (US, GB, AU, etc.)	US
genreFilter	string	Filter by genre in browse mode	all
statusFilter	string	Filter by airing status (Running, Ended, etc.)	all
maxItems	integer	Maximum records to emit (1–5,000)	50

Modes

Mode	Description
searchShows	Search TV shows by name or keyword
browseShows	Browse all shows with optional genre/status filtering
episodes	Get all episodes for a specific show (provide showId)
schedule	Tonight's TV schedule — both streaming and broadcast
people	Browse actors and directors

Output

Show record

{
  "id": 169,
  "url": "https://www.tvmaze.com/shows/169/breaking-bad",
  "name": "Breaking Bad",
  "type": "Scripted",
  "language": "English",
  "genres": ["Drama", "Crime", "Thriller"],
  "status": "Ended",
  "runtime": 60,
  "premiered": "2008-01-20",
  "ended": "2013-09-29",
  "rating": 9.2,
  "networkName": "AMC",
  "networkCountry": "US",
  "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/81/202627.jpg",
  "imageOriginal": "https://static.tvmaze.com/uploads/images/original_untouched/81/202627.jpg",
  "summary": "Breaking Bad is an American crime drama television series.",
  "imdbId": "tt0903747",
  "thetvdbId": 81189,
  "officialSite": "http://www.amc.com/shows/breaking-bad",
  "recordType": "show",
  "scrapedAt": "2024-01-15T14:30:00+00:00"
}

Episode record

{
  "episodeId": 4952,
  "showId": 82,
  "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming",
  "name": "Winter is Coming",
  "season": 1,
  "episodeNumber": 1,
  "type": "regular",
  "airdate": "2011-04-17",
  "airtime": "21:00",
  "airstamp": "2011-04-18T01:00:00+00:00",
  "runtime": 60,
  "rating": 8.2,
  "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/...",
  "summary": "Jon Snow is given a harsh lesson in survival.",
  "recordType": "episode",
  "scrapedAt": "2024-01-15T14:30:00+00:00"
}

Person record

{
  "id": 1,
  "url": "https://www.tvmaze.com/people/1/mike-vogel",
  "name": "Mike Vogel",
  "gender": "Male",
  "birthday": "1979-07-17",
  "country": "United States",
  "countryCode": "US",
  "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/0/1.jpg",
  "recordType": "person",
  "scrapedAt": "2024-01-15T14:30:00+00:00"
}

Output Fields

Field	Type	Description
id / episodeId	integer	TVmaze unique identifier
url	string	TVmaze page URL
name	string	Show or episode title
type	string	Show type (Scripted, Reality, Animation, etc.)
language	string	Primary language
genres	array	Genre tags
status	string	Airing status (Running, Ended, etc.)
runtime	integer	Episode runtime in minutes
premiered	string	Premiere date (YYYY-MM-DD)
ended	string	End date if concluded
rating	number	Average user rating (0–10)
networkName	string	Broadcast network
networkCountry	string	Network country code
webChannel	string	Streaming platform (Netflix, Hulu, etc.)
imageMedium	string	Medium poster/image URL
imageOriginal	string	Full-size poster/image URL
summary	string	Plain-text description (HTML removed)
imdbId	string	IMDb cross-reference ID
thetvdbId	integer	TheTVDB cross-reference ID
recordType	string	show, episode, person, or schedule
scrapedAt	string	ISO 8601 UTC scrape timestamp

All fields are omit-empty — null or empty fields are not included in output.

Use Cases

• TV recommendation systems — Build a show database with genres, ratings, and metadata.
• Episode trackers — Get full episode lists with air dates, numbers, and synopses.
• Streaming research — Identify which shows air on which networks and platforms.
• Content calendars — Pull today's TV schedule to see what's on.
• Show database enrichment — Use IMDb and TheTVDB IDs for cross-referencing.
• Cast research — Build a directory of TV actors with biographical data.

Example Inputs

Search for a show

{ "mode": "searchShows", "query": "the wire", "maxItems": 10 }

Browse all drama shows currently running

{
  "mode": "browseShows",
  "genreFilter": "Drama",
  "statusFilter": "Running",
  "maxItems": 100
}

Get all episodes of Breaking Bad (show ID 169)

{ "mode": "episodes", "showId": 169, "maxItems": 100 }

Tonight's US schedule

{ "mode": "schedule", "scheduleCountry": "US", "maxItems": 100 }

Browse actors

{ "mode": "people", "maxItems": 200 }

Data Source

Data is sourced from the TVmaze REST API (api.tvmaze.com), a free public API covering 50,000+ TV shows worldwide. The API requires no authentication for basic public access (rate limit: 20 calls/10 seconds for anonymous users).

FAQs

Do I need an API key? No. TVmaze's public REST API is free and requires no authentication for basic data access.

How do I find a show's ID? Run in searchShows mode — the id field in results is the TVmaze show ID to use in episodes mode.

Can I get show images? Yes. Both imageMedium (210×295 px) and imageOriginal (full resolution) URLs are included for shows, episodes, and people.

Why might some shows not have ratings? Shows without enough user ratings on TVmaze will not have a rating field in the output (the actor omits empty/zero values).

What's the difference between streaming and broadcast schedules? In schedule mode, the actor fetches both the web/streaming schedule (Netflix, Hulu, Amazon, etc.) and the traditional broadcast schedule for the selected country.

Are episode summaries plain text? Yes. The actor automatically strips HTML tags from summaries, so the output is always clean plain text.