How to Scrape TVMaze TV Show & Episode Data in 2026

If you’re building a TV analytics dashboard, training a recommendation model, or powering a “what’s on tonight” feature, you need structured show data: genres, networks, ratings, full episode lists, cast, and a daily schedule. The obvious commercial APIs are metered and keyed. TVMaze, by contrast, runs a free and fully open REST API — no key, no OAuth, no login — that covers shows, episodes, cast, people, and country-level schedules. The catch is that its responses are nested and endpoint-specific: the show index paginates one way, episodes come per-show, cast is a separate call, and schedules join across resources. This guide covers what TVMaze exposes and how to pull flat, analysis-ready TV data from it.

What’s worth extracting

The scraper flattens TVMaze responses into clean rows, 40+ fields across the modes. Every row carries three universal fields plus mode-specific data:

Universal (on every item):

• _mode — which mode produced the row, so you can mix modes in one dataset and filter later.
• url — a clean link back to the TVMaze page.
• scrapedAt — an ISO 8601 scrape timestamp.

Shows (showIndex, searchShows, showDetails):

• id, name, type (Scripted, Animation, Reality…), language, genres (array), status (Running/Ended/TBD), premiered/ended, rating (TVMaze average), network, runtime, image (poster), an HTML-stripped summary, and imdbId — plus a TheTVDB cross-reference ID from TVMaze’s externals.

Episodes (episodes): showName, season, number, name, airdate, runtime, per-episode rating, and summary.

Cast (cast): showName, personName, characterName, personCountry, personBirthday, personGender, self/voice boolean flags, and personUrl.

Schedule (schedule): airdate, airtime, showName, showNetwork, season/number, episode name, showGenres, and showRating.

People (people): id, name, country, birthday/deathday, gender, and image.

How the source works

The scraper calls the open TVMaze REST API directly over HTTP — no headless browser. Seven modes share one input form, and each maps to a TVMaze endpoint:

• showIndex — paginate the entire TVMaze catalogue at 250 shows per page. This is the high-volume mode for building a complete shows dataset.
• searchShows / people — free-text search for shows or people by name.
• showDetails — rich metadata for a show (or a batch via showIds), optionally with an embedded cast[] list.
• episodes — every episode of a series by showId.
• cast — cast-to-character mappings for a show.
• schedule — a full day of airings for a country, each joined to its show’s network, genres, and rating.

Building a catalogue dataset needs almost nothing:

{
  "mode": "showIndex",
  "startPage": 0,
  "maxResults": 500
}

Pulling every episode of a long-running series (here The Simpsons, show ID 83):

{
  "mode": "episodes",
  "showId": "83",
  "maxResults": 2000
}

Today’s US TV schedule for an EPG feature:

{
  "mode": "schedule",
  "country": "US",
  "date": "2026-07-06"
}

The ID-based modes (showDetails, episodes, cast) need a numeric showId — the integer in a TVMaze show URL (tvmaze.com/shows/169/... gives 169). Person modes need a personId. The usual workflow is searchShows or people first to discover IDs, then feed them into the detail modes.

The access reality

TVMaze is a free, open API built for developers, so there’s no anti-bot wall — the friction is structural, in how the data is shaped and split:

• Data is endpoint-specific, and modes fill different fields. A schedule row has airtime and showNetwork; an episodes row has season and per-episode rating; a cast row has characterName. You can’t get episode-level ratings from the show index — you have to run episodes mode. The _mode tag on every row exists precisely so you can keep multiple modes in one dataset and filter them apart afterward.
• IDs are the join key, and you usually discover them first. Most detail modes are ID-driven. If you don’t already have show IDs, the natural first step is a searchShows pass to resolve names to IDs, then the ID-based modes. Building this yourself means a two-step pipeline.
• showIndex is the volume path; other modes are targeted. Only showIndex guarantees bulk output — it walks the whole catalogue 250 at a time, and a single run can pull thousands of shows by raising maxResults. episodes, cast, and schedule are scoped to one show or one day.
• Summaries arrive as HTML. TVMaze returns summary fields wrapped in HTML tags. The scraper strips them to plain text, so you don’t have to sanitize markup downstream.
• No key, but respect the source. No auth is required, but you’re still hitting a community-run API. The scraper reads it over plain HTTP at a reasonable pace.

▶ Run the TVMaze Scraper on Apify — one run pulls a catalogue of shows, a full episode list, a day’s TV schedule, or cast mappings from the open TVMaze API. No key, no browser, no login. Export to JSON, CSV, or Excel.

Example output

A trimmed showDetails record for Breaking Bad:

{
  "_mode": "showDetails",
  "id": 169,
  "name": "Breaking Bad",
  "type": "Scripted",
  "language": "English",
  "genres": ["Drama", "Crime", "Thriller"],
  "status": "Ended",
  "premiered": "2008-01-20",
  "ended": "2013-09-29",
  "runtime": 60,
  "rating": 9.2,
  "network": "AMC",
  "imdbId": "tt0903747",
  "image": "https://static.tvmaze.com/uploads/images/original_untouched/0/2400.jpg",
  "summary": "Breaking Bad follows protagonist Walter White, a chemistry teacher...",
  "url": "https://www.tvmaze.com/shows/169/breaking-bad",
  "scrapedAt": "2026-07-06T14:00:00.000Z"
}

The imdbId (tt0903747) is what lets you join TVMaze rows to IMDb or TheTVDB datasets — the cross-reference that makes TVMaze useful as an enrichment source, not just a standalone one.

Use cases

• TV and streaming analytics — build a shows dataset with genres, networks, premiere years, and ratings, then chart trends in a BI tool.
• Recommendation engines and ML — bulk-ingest shows, genres, ratings, and cast to train content-based or collaborative recommenders.
• EPG / what’s-on apps — pull a country’s daily schedule (a single US day returns well over 100 airings) to power an electronic program guide.
• Catalog enrichment — enrich your own media catalog with TVMaze metadata, posters, runtimes, networks, and IMDb/TheTVDB cross-IDs via showDetails.
• Market and competitor research — track which networks air the most shows, benchmark a series’ episode ratings over time, or monitor a genre’s back catalog.
• AI agents and RAG — wrap the actor as a tool so an LLM can answer “what sci-fi shows air on the BBC?” or embed show summaries for retrieval.

Cost and effort: build vs. managed

The TVMaze API is free and keyless, so the trade-off is purely engineering time:

• Building from scratch — you’d learn seven endpoints and their differing shapes, write the showIndex pagination (250/page), build the search-then-ID two-step pipeline, join schedule rows to show metadata, strip HTML from summaries, and flatten nested genre and external-ID structures. Each mode is a small task; together they add up.
• Using the managed actor — pick a mode, fill the fields it needs, run. Pricing is pay-per-result: a fraction of a cent per record, plus a trivial per-run start fee. A 500-show catalogue crawl or a full episode list costs a few cents.

The value is that all seven modes, the pagination, the HTML stripping, and the cross-reference IDs are already wired into one form — you don’t rebuild the plumbing for each mode.

Common pitfalls

Specifics of TVMaze that catch people out:

• You can’t get everything from one mode. The most common mistake is expecting episode ratings or cast from the show index. Those live in episodes and cast modes. Plan which modes you need up front, and use _mode to keep them straight in a combined dataset.
• IDs come from a search step, not thin air. If you don’t have show or person IDs, run searchShows/people first. Feeding a wrong showId into episodes returns the wrong show’s episodes, silently.
• genres and showGenres are arrays. Show rows carry genres as a JSON array. If you’re exporting to a flat CSV, decide how to serialize the array (join on a delimiter) rather than assuming a single value.
• Ratings can be null. The TVMaze rating average isn’t set for every show or episode. Treat a null rating as “unrated,” not as zero, or you’ll skew any average you compute.
• Schedule is one country, one day. schedule mode returns a single country’s airings for a single date. To build a week or cover multiple countries, run it once per day/country and combine — it isn’t a bulk range query.
• showIndex is the only guaranteed high-volume mode. If you need thousands of rows, that’s the mode to use, raising maxResults. The targeted modes are scoped by design and won’t fill a large dataset on their own.

Wrapping up

TVMaze gives you a genuinely open, keyless TV data source — the work is in its seven endpoint shapes and the search-then-detail pattern, not in getting past any wall. If you want one show’s metadata, hit the API directly. If you want a catalogue-scale dataset, full episode lists, daily schedules, and cast with IMDb cross-references all in one consistent, flattened output, a managed actor collapses the seven modes into one form and hands you clean rows.

▶ Open the TVMaze Scraper on Apify — one run yields a TV shows dataset, a full episode list, a day’s schedule, or cast mappings with IMDb IDs; no key, no browser, no login. Export to JSON, CSV, or Excel, and start on Apify’s free monthly credit.