TVMaze Scraper — TV Show, Series, Episode, Cast & TV Schedule Data (No API Key)

▶️ Run on Apify

Documentation only. This repository contains usage guides, code examples, and integration recipes for the hosted TVMaze Scraper Actor on the Apify platform. It does not contain the Actor's source code. The Actor runs entirely on Apify — you call it from your own code or the Apify Console.

---

Scrape structured TV show, TV series, episode, cast, and TV schedule data with a single Apify Actor. The TVMaze Scraper turns entertainment metadata into clean, flat JSON: search TV shows by name, pull full show details and ratings, complete episode lists, cast and characters, people/actor records, and a whole country's daily TV air schedule (EPG). Get fields like name, genres[], network, premiered, rating, imdbId, season, number, airdate, and more — ready for analytics, machine learning, recommendation engines, and TV guide apps.

No API key, no login, no OAuth. You only need an Apify account. Seven modes share one input form, every result is tagged with _mode so you can mix modes in a single dataset, and a single run can return thousands of records — from the entire show catalogue down to one episode. Export TV datasets to JSON, CSV, Excel, XML, or JSONL, or pull them straight from the Apify API into your data pipeline.

Use it as a practical TVMaze API alternative / TV database API when you want structured JSON, ready-made CSV/Excel exports, and out-of-the-box dataset views without writing your own pagination and flattening.

---

📊 What you get (output fields)

Every run streams flattened records into your Apify dataset, tagged per mode. The Actor exposes six pre-built dataset views — Overview, Shows, Episodes, Cast, Schedule, People — so you can slice the data with zero post-processing.

Universal fields (on every item)

Field	Description
_mode	Which mode/endpoint produced the row (filter or pivot on it)
id	TVMaze numeric ID for the show/person
name	Show, episode, or person name
url	Clean link back to the TVMaze page
scrapedAt	Scrape timestamp (ISO 8601)

Shows — showIndex, searchShows, showDetails

Field	Description
id	TVMaze show ID
name	Show / series name
type	Show type (e.g. Scripted, Animation, Reality)
language	Original language
genres	Array of genres
status	Running / Ended / To Be Determined
premiered	Premiere date
ended	End date
rating	TVMaze average rating
network	Airing network
runtime	Episode runtime in minutes
imdbId	IMDb cross-reference ID
image	Poster image URL
summary	Show summary (HTML-stripped)
url	TVMaze show URL

Episodes — episodes

Field	Description
showName	Series name
season	Season number
number	Episode number
name	Episode title
airdate	Air date
runtime	Episode runtime in minutes
rating	Per-episode rating
summary	Episode summary
url	TVMaze episode URL

Cast — cast

Field	Description
showName	Show the cast belongs to
personName	Actor name
characterName	Character played
personCountry	Actor's country
personBirthday	Actor's birthday
personGender	Actor's gender
self	Appears as themselves (boolean)
voice	Voice role (boolean)
personUrl	Actor's TVMaze URL

Schedule — schedule

Field	Description
airdate	Air date
airtime	Air time
showName	Show that airs
showNetwork	Network
season	Season number
number	Episode number
name	Episode title
showGenres	Show genres
showRating	Show rating
url	TVMaze URL

People — people

Field	Description
id	TVMaze person ID
name	Person / actor name
country	Country
birthday	Birth date
deathday	Death date
gender	Gender
image	Photo URL
url	TVMaze person URL

---

💡 Use cases

• Build a TV guide / EPG app — pull a country's daily TV schedule with air times, networks, and episode titles to power a "what's on tonight" electronic program guide.
• Entertainment dataset for machine learning — crawl the full TVMaze catalogue at scale to train models on shows, genres, ratings, networks, and premiere years.
• Episode tracking & progress apps — fetch complete episode lists with season/episode numbers, air dates, and per-episode ratings to drive watch-tracking features.
• Cast & actor databases — map every cast member to the character they play, with country, birthday, and photos, to build filmographies and actor pages.
• Streaming catalog enrichment — enrich your own media catalog with TVMaze metadata, posters, runtimes, networks, and IMDb cross-reference IDs.
• Recommendation engines — bulk-ingest shows, genres, ratings, and cast to power content-based or collaborative TV recommenders.
• Media & market research — track which networks air the most shows, benchmark a series' episode ratings, or analyze a genre's back catalog.
• AI agents & RAG — wrap the Actor as a tool so an LLM can answer questions like "what sci-fi shows air on the BBC tonight?" or embed show summaries for retrieval.

---

🚀 Quick start

You can run the TVMaze Scraper from the Apify Console, the Apify CLI, the REST API, or the official JavaScript/Python clients. All four call the hosted Actor — you never run scraping code yourself.

1. Apify Console (no code)

1. Open the Actor: apify.com/logiover/tvmaze-scraper.
2. Click Try for free.
3. Pick a Mode (e.g. showIndex, episodes, schedule) and fill only the fields that mode needs.
4. Click Start. When the run finishes, open the Output tab, switch between the Overview / Shows / Episodes / Cast / Schedule / People views, and Export to JSON, CSV, Excel, XML, or JSONL.

2. Apify CLI

# Install the Apify CLI
npm install -g apify-cli

# Log in with your Apify API token (from apify.com/account/integrations)
apify login

# Run the actor with an input file, then fetch the dataset
apify call logiover/tvmaze-scraper --input-file=input.json

Example input.json — crawl the catalogue for a big TV shows dataset:

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

See examples/cli.md for more.

3. REST API (curl)

Run the Actor synchronously and get the dataset items back in one call:

curl -X POST "https://api.apify.com/v2/acts/logiover~tvmaze-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "episodes",
    "showId": "83",
    "maxResults": 2000
  }'

Full async run + poll + pagination examples are in examples/api-curl.md.

4. apify-client (JavaScript & Python)

JavaScript / Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('logiover/tvmaze-scraper').call({
  mode: 'schedule',
  country: 'US',
  date: '2026-07-06',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("logiover/tvmaze-scraper").call(run_input={
    "mode": "searchShows",
    "query": "breaking bad",
    "maxResults": 50,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["name"], item.get("rating"))

More detail in examples/javascript.md and examples/python.md.

---

📥 Input

Pick a Mode, then set only the fields that mode uses. The input form shows which fields apply to each mode.

Field	Type	Required	Description
mode	string (select)	No (default showIndex)	Which TVMaze endpoint to run. One of: showIndex, searchShows, showDetails, episodes, cast, schedule, people.
query	string	For searchShows / people	Free-text term — a show name (searchShows) or a person name (people).
showId	string	For showDetails / episodes / cast	A single numeric TVMaze show ID, e.g. 169 (Breaking Bad) or 83 (The Simpsons).
showIds	array of strings	For batch showDetails	Batch of TVMaze show IDs for showDetails. Default [].
embedCast	boolean	Optional (showDetails)	When true, showDetails also attaches a compact cast[] list (actor + character) to each show. Default false.
personId	string	For people	A single numeric TVMaze person ID, e.g. 1.
personIds	array of strings	For batch people	Batch of TVMaze person IDs. Default [].
country	string (select)	For schedule	ISO 3166-1 alpha-2 country code, e.g. US, GB, CA, AU, DE, TR, JP. Default US. Large TV markets return the most airings.
date	string	Optional (schedule)	Day to pull the schedule for, format YYYY-MM-DD. Empty = today.
startPage	integer	Optional (showIndex)	0-based page to start showIndex pagination from (250 shows per page). Default 0. Use it to resume or skip ahead.
maxResults	integer	Optional (all modes)	Upper bound on rows returned. Drives pagination for showIndex; caps the list for other modes. Default 250 (min 1, max 500000).

The seven modes

Mode	What it does	Key fields to set
showIndex	The full TVMaze catalogue, 250 shows per page, paginated — the highest-volume mode (default).	startPage, maxResults
searchShows	Free-text search for TV shows by name.	query
showDetails	Full details for one or more show IDs (batch), with optional cast embed.	showId or showIds, embedCast
episodes	Every episode of a series (a long-running show returns hundreds).	showId
cast	Cast members and the characters they play, for a show.	showId
schedule	A full day of TV airings for a country (100+ across the US).	country, date
people	Free-text people search, or details for one/more person IDs.	query or personId / personIds

Tip — finding IDs: a show ID is the integer in a TVMaze show URL (tvmaze.com/shows/169/... → 169); a person ID is the integer in a person URL (tvmaze.com/people/1/... → 1). Use searchShows or people search first to discover IDs, then feed them into showDetails, episodes, cast, or people.

---

📤 Output

Results stream to the default dataset, flattened per mode, with every item tagged by _mode. Here is a trimmed sample show record (showDetails mode):

{
  "_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"
}

And a trimmed sample schedule record (schedule mode):

{
  "_mode": "schedule",
  "airdate": "2026-07-06",
  "airtime": "22:00",
  "showName": "Some Series",
  "showNetwork": "AMC",
  "season": 3,
  "number": 5,
  "name": "The Episode Title",
  "showGenres": ["Drama", "Thriller"],
  "showRating": 8.1,
  "url": "https://www.tvmaze.com/episodes/...",
  "scrapedAt": "2026-07-06T14:00:00.000Z"
}

Column layout differs per mode — see the field tables in What you get above, or the built-in dataset views on the run's Output tab.

---

⏰ Integrations & automation

• Schedules — use Apify Schedules to run the Actor daily or weekly, e.g. refresh a TV shows dataset every night, or snapshot the daily schedule for an EPG feed each morning.
• Webhooks — trigger an Apify webhook on run completion to notify your backend, kick off a downstream job, or post to Slack when new episode data is ready.
• Google Sheets — push results into Google Sheets with the Apify Google Sheets integration for a live, shareable TV dataset.
• Amazon S3 / cloud storage — export the dataset to S3 (or any store) for archival and downstream ETL.
• No-code automation — connect via Zapier, Make, n8n, or Pipedream using Apify's integrations to build media pipelines without writing glue code.
• Your own stack — call the Actor from JavaScript or Python with apify-client, or hit the REST API directly (run-sync-get-dataset-items) from any language.

---

📦 Export formats

Datasets can be downloaded or fetched via API in any of these formats:

• JSON — full structured records.
• CSV — spreadsheet-friendly, one row per record.
• JSONL (JSON Lines) — one JSON object per line, ideal for streaming/ETL.
• Excel (XLSX) — open directly in Excel or Google Sheets.
• XML — for legacy systems and feeds.

---

❓ FAQ

How do I scrape TV show data without writing a scraper?

Run the hosted TVMaze Scraper Actor on Apify. Pick a mode (for example showIndex for the whole catalogue or searchShows to find shows by name), start the run, and export the results as JSON, CSV, or Excel. You never write or host any scraping code yourself.

Is this a TVMaze API alternative / TV database API?

Yes — effectively both. It works as a convenient wrapper that returns structured TV show, episode, cast, and schedule data as clean JSON, with ready-made CSV/Excel exports and dataset views, so you don't have to build your own pagination and flattening.

Do I need a TVMaze API key or account?

No TVMaze API key, no OAuth, and no login are required. You only need an Apify account and your Apify API token to call the Actor.

Is it free?

The Actor runs on a pay-per-result model, and you can try it on Apify's free tier first. Check the Pricing tab on the Actor page for the current rate.

How do I get episode lists with air dates and ratings?

Use episodes mode and set the numeric showId (for example 83 for a long-running animated series). The Actor returns every episode with season and episode numbers, air dates, runtimes, per-episode ratings, and summaries.

How do I get cast and characters?

Use cast mode with a showId to get every cast member mapped to the character they play (with self/voice flags and photos). Alternatively, set embedCast: true in showDetails to attach a compact cast list to each show.

How do I get a TV schedule / what's-on-tonight data?

Use schedule mode with a country code (e.g. US, GB, DE) and an optional date in YYYY-MM-DD format (empty = today). A single US day returns well over 100 airings, each joined to its show's network, genres, and rating — perfect for an EPG or "what's on" feature.

How do I export TV series data to CSV or Excel?

Run any mode, then download the dataset as CSV, JSON, JSONL, Excel (XLSX), or XML from the run's Output tab, or fetch it via the Apify API. This makes it a simple TV show data export and dataset tool.

How many shows can I scrape?

showIndex paginates the entire TVMaze catalogue at 250 shows per page, so a single run can pull thousands of shows into one dataset — just raise maxResults (up to 500000). It is the guaranteed high-volume mode and the default.

How do I find a TVMaze show ID or person ID?

A show ID is the integer in a TVMaze show URL (tvmaze.com/shows/169/... → 169), and a person ID is the integer in a person URL (tvmaze.com/people/1/... → 1). Use searchShows or people search first to discover IDs, then feed them into the ID-based modes.

Can I join TVMaze data to IMDb?

Yes. Every show row includes an imdbId cross-reference field, so you can join TVMaze data to IMDb datasets (for example, from the IMDb Scraper).

Is it legal to use this TVMaze scraper?

The Actor reads only publicly available data. You are responsible for using the data in compliance with the source's terms of service, GDPR, and any applicable local laws.

---

🔗 Related actors by logiover

Building a full entertainment dataset? Pair the TVMaze Scraper with the rest of the media suite:

Actor	What it does
IMDb Scraper	Movie & TV titles, ratings, and metadata from IMDb
MyAnimeList Anime Scraper	Anime titles, scores, and metadata from MyAnimeList

👉 Browse all logiover scrapers on Apify Store.

---

📄 Documentation only — the Actor runs on the Apify platform. ▶️ Run it: https://apify.com/logiover/tvmaze-scraper

Licensed under the MIT License.