# TVMaze Scraper — TV Shows, Episodes, Cast & Schedule API (`logiover/tvmaze-scraper`) Actor

TV show data API powered by the open TVMaze REST API — no key, no browser. Search shows, pull show details, ratings, full episode lists, cast & characters, people and a country's daily TV air schedule. Export TV datasets to JSON, CSV or Excel for analytics, ML and recommendations.

- **URL**: https://apify.com/logiover/tvmaze-scraper.md
- **Developed by:** [Logiover](https://apify.com/logiover) (community)
- **Categories:** Videos, Business, Developer tools
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

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

![Apify Actor](https://img.shields.io/badge/Apify-Actor-00A67E?logo=apify\&logoColor=white) ![No API key](https://img.shields.io/badge/No%20API%20key-required-2ea44f) ![Pay per result](https://img.shields.io/badge/Pricing-Pay%20per%20result-1C7ED6) ![TV & Media](https://img.shields.io/badge/Category-TV%20%26%20Media-8B5CF6) ![Export](https://img.shields.io/badge/Export-JSON%20%7C%20CSV%20%7C%20Excel-F59E0B)

***

A **TVMaze scraper** and structured **TV show data API** in a single Apify Actor. Search TV shows, pull full **show details and ratings**, complete **episode lists**, **cast and characters**, **people**, and a whole country's daily **TV air schedule** — powered directly by the free, open **TVMaze REST API**. Get `name`, `genres[]`, `network`, `premiered`, `rating`, `imdbId`, `season`/`number`, `airdate` and more as clean, flat JSON. **No API key, no login, no OAuth, no headless browser — just fast HTTP.** Seven modes share one input form, and every result is tagged with `_mode` so you can mix modes in one dataset and filter later.

> ### 🏆 Why this TVMaze scraper?
>
> **7 modes · 40+ fields across shows, episodes, cast, schedule & people** · thousands of records per run · direct calls to the open TVMaze REST API (no browser) · export to JSON / CSV / Excel. The convenient **TV database API alternative** for analytics, ML, recommendations and EPG apps.

### ✨ What this Actor does / Key features

- 📺 **Full catalogue crawl** — `showIndex` mode paginates the entire TVMaze catalogue at **250 shows per page**, the fastest way to build a complete TV shows dataset.
- 🔎 **Free-text search** — find shows or people by name with `searchShows` and `people`.
- 🧾 **Rich show details** — `name`, `type`, `language`, `genres[]`, `status`, `premiered`/`ended`, `runtime`, `network`, `officialSite`, `imdbId`, `image` and an HTML-stripped `summary`; optionally embed the cast.
- 🎬 **Complete episode lists** — every episode of a series with `season`, `number`, `airdate`, `runtime`, per-episode `rating` and `summary`.
- 🎭 **Cast & characters** — each cast member mapped to the `characterName` they play, with `self`/`voice` flags and photos.
- 🗓️ **Daily TV schedule** — a full day of airings for any `country` (100+ across the US), each joined to its show's network, genres and rating.
- 👤 **People lookups** — `name`, `country`, `birthday`, `deathday`, `gender` and photo, by search or by ID.
- ⭐ **Ratings everywhere** — the TVMaze `rating` average on every show and episode row.
- 🔗 **Cross-reference IDs** — every show row carries `imdbId` (and TheTVDB) so you can join TVMaze data to IMDb/TheTVDB datasets.
- 🏷️ **Universal tagging** — clean `url` back to TVMaze plus `_mode` and `scrapedAt` (ISO 8601) on every item; six pre-built dataset views slice the data with zero post-processing.

### 🚀 Quick start (3 steps)

1. **Configure** — pick a **Mode** and fill only the fields that mode needs (e.g. `mode: showIndex` needs nothing else; `mode: episodes` needs a `showId`).
2. **Run** — click **Start**. The Actor calls the TVMaze REST API, flattens the response and streams rows into your dataset.
3. **Get your data** — open the **Output** tab, switch between the Overview / Shows / Episodes / Cast / Schedule / People views, and export to **JSON, CSV, Excel, HTML, RSS or JSON Lines** — or pull it via the Apify API.

### 📥 Input

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

#### Example — crawl the catalogue for a big TV shows dataset

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

#### Example — every episode of a long-running series

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

#### Example — today's US TV schedule (EPG / what's-on)

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

| Field | Type | Description |
|-------|------|-------------|
| `mode` | string | Which TVMaze endpoint to run: `showIndex`, `searchShows`, `showDetails`, `episodes`, `cast`, `schedule` or `people`. **Required.** Default `showIndex`. |
| `query` | string | Free-text term for `searchShows` (a show name) or `people` (a person name). |
| `showId` | string | Numeric TVMaze show ID, e.g. `169` (Breaking Bad) or `83` (The Simpsons). Used by `showDetails`, `episodes`, `cast`. |
| `showIds` | array | Batch of TVMaze show IDs (integers) for `showDetails`. |
| `embedCast` | boolean | When true, `showDetails` also attaches a compact `cast[]` list (actor + character) to each show. Default `false`. |
| `personId` | string | Numeric TVMaze person ID, e.g. `1`. Used by `people`. |
| `personIds` | array | Batch of TVMaze person IDs for `people` lookups. |
| `country` | string | ISO 3166-1 alpha-2 country code for `schedule` (e.g. `US`, `GB`, `DE`, `TR`). Default `US`. |
| `date` | string | Day for `schedule`, format `YYYY-MM-DD`. Empty = today. |
| `startPage` | integer | 0-based page to start `showIndex` pagination from (250 shows/page). Default `0`. |
| `maxResults` | integer | Upper bound on rows. Drives pagination for `showIndex`; caps the list for other modes. Default `250`. |

> **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 **40+ fields across the modes** and every item tagged with `_mode`. Here is a trimmed sample **show** record:

```json
{
  "_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",
  "officialSite": "http://www.amc.com/shows/breaking-bad",
  "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"
}
```

<details>
<summary><b>📋 Full field reference (click to expand)</b></summary>

**Universal (every item)**

| Field | Description |
|-------|-------------|
| `_mode` | Which mode/endpoint produced the row (filter or pivot on it) |
| `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 name |
| `type` | Show type (e.g. Scripted, Animation, Reality) |
| `language` | Original language |
| `genres` | Array of genres |
| `status` | Running / Ended / To Be Determined |
| `premiered` / `ended` | Premiere and end dates |
| `rating` | TVMaze average rating |
| `network` | Airing network |
| `runtime` | Episode runtime in minutes |
| `imdbId` | IMDb cross-reference ID (TheTVDB ID also included from `externals`) |
| `image` | Poster image URL |
| `summary` | HTML-stripped show summary |

**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 |

**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` / `number` | Season and episode numbers |
| `name` | Episode title |
| `showGenres` | Show genres |
| `showRating` | Show rating |

**People — `people`**

| Field | Description |
|-------|-------------|
| `id` | TVMaze person ID |
| `name` | Person name |
| `country` | Country |
| `birthday` / `deathday` | Birth and death dates |
| `gender` | Gender |
| `image` | Photo URL |

</details>

### 💡 Use cases

- **TV & streaming analytics** — build a TV shows dataset with genres, networks, premiere years and ratings, then chart trends in a BI tool.
- **Recommendation engines & 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 TV schedule to power an electronic program guide or "what's on tonight" feature.
- **Catalog enrichment** — enrich your own media catalog with TVMaze metadata, posters, runtimes, networks and IMDb/TheTVDB cross-IDs via `showDetails`.
- **Market & competitor research** — track which networks air the most shows, benchmark a series' episode ratings, or monitor a genre's back catalog.
- **AI agents & 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.

### 👥 Who uses it

TV & streaming analysts · recommendation-engine & ML developers · EPG / "what's-on" app builders · media-catalog & metadata teams · data journalists & researchers · AI-agent and RAG developers.

### 💰 Pricing

This Actor runs on a simple **pay-per-result** model — you pay for the records you extract, with no separate Apify platform fees to calculate. Try it on the **free tier** first, then scale up. See the **Pricing** tab on this page for the current rate.

### ❓ Frequently Asked Questions

#### Do I need a TVMaze API key or account?

No. TVMaze offers a free, open REST API and this Actor reads it directly. You only need an Apify account — no TVMaze API key, no OAuth, no login.

#### Is this a TVMaze API or a TV database API alternative?

Both, effectively. It works as a convenient wrapper over the **TVMaze API** and as a practical **TV database API** for teams who want structured JSON, ready-made CSV/Excel exports and dataset views without writing their own pagination and flattening.

#### How do I scrape TV episodes without an API key?

Pick `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 — no key or login required.

#### How do I get a TVMaze show ID or person ID?

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 the ID-based modes.

#### How do I export TV show data to CSV, JSON or Excel?

Run any mode and download the dataset as CSV, JSON, Excel (XLSX), HTML, RSS or JSON Lines from the run page, or pull it via the Apify API. This makes it a simple **TV show data export** and TV dataset tool.

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

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

#### How much data can the show index return?

`showIndex` paginates the entire TVMaze catalogue at 250 shows per page. A single run can pull thousands of shows into one dataset — just raise `maxResults`. It's the guaranteed high-volume mode and the default.

#### Does it cover cast and characters?

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

#### Can I get IMDb and TheTVDB IDs too?

Yes. Every show row includes `imdbId` and TheTVDB cross-reference IDs from TVMaze's `externals`, so you can join TVMaze data to IMDb or TheTVDB datasets.

#### Is it legal to use this TVMaze scraper?

The Actor reads only publicly available data from the open TVMaze REST API. You are responsible for using the data in compliance with TVMaze's terms and applicable laws such as GDPR.

### 🔗 More media & entertainment scrapers by logiover

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

| Actor | What it does |
|---|---|
| [IMDb Scraper](https://apify.com/logiover/imdb-scraper) | Movie & TV titles, ratings and metadata from IMDb |
| [Letterboxd Film Review Scraper](https://apify.com/logiover/letterboxd-film-review-scraper) | Film reviews and ratings from Letterboxd |
| [MyAnimeList Anime Scraper](https://apify.com/logiover/mal-anime-scraper) | Anime titles, scores and metadata from MyAnimeList |
| [Discogs Scraper](https://apify.com/logiover/discogs-scraper) | Music releases, artists and labels from Discogs |
| [Twitch Scraper](https://apify.com/logiover/twitch-scraper) | Live streams, channels and category data from Twitch |
| [Steam Game Reviews Scraper](https://apify.com/logiover/steam-game-reviews-scraper) | Game reviews and ratings from Steam |
| [Apple Podcasts Episode Scraper](https://apify.com/logiover/apple-podcasts-episode-scraper) | Podcast shows and episode metadata |
| [YouTube Channel Scraper](https://apify.com/logiover/youtube-channel-scraper) | All videos of a YouTube channel |
| [YouTube Video Details Scraper](https://apify.com/logiover/youtube-video-details-scraper) | Full metadata for any YouTube video |
| [Resident Advisor Scraper](https://apify.com/logiover/resident-advisor-scraper) | Electronic-music events and artists |

👉 Browse all **[logiover scrapers on Apify Store](https://apify.com/logiover)** — 180+ actors across real estate, jobs, crypto, social media & B2B data.

### ⏰ Scheduling & integration

Schedule this Actor on Apify to refresh a TV dataset daily or weekly, or to snapshot the daily schedule for an EPG feed. Export results to JSON, CSV, Excel, HTML, RSS or JSON Lines, sync to Google Sheets, or push to your database, BI tools and webhooks through the Apify API. Call it from your stack via `run-sync-get-dataset-items`, the JavaScript/Python clients, or no-code tools like **Make, n8n and Zapier** to build automated media pipelines.

### ⭐ Support & feedback

Found a bug or need an extra field or mode? Open an issue on the **Issues** tab — response is usually within 24 hours. If this Actor saves you time, a **★★★★★ review** on the Store page genuinely helps and is hugely appreciated. 🙏

### ⚖️ Legal

This Actor reads only publicly available data from the open TVMaze REST API and is intended for legitimate research, analytics and product-development use. You are responsible for complying with TVMaze's terms of service, GDPR and any applicable local laws.

***

### 📝 Changelog

#### 2026-08-01

- Completed the August 2026 full health check: verified empty/programmatic default, Console UI default, and two source-informed alternative inputs on Apify.
- Confirmed successful live execution, non-empty structured output, dataset-field/type integrity, and logical sample quality within the 5-minute quality window.
- Declared 24 dataset fields from typed live cloud samples so the output contract is no longer an empty placeholder.
- Declared 33 nullable dataset fields from typed live cloud samples so the output contract is no longer an empty placeholder or brittle to sparse modes.
- Added the source-emitted conditional cast/person and schedule fields claimed by the README, with nullable scalar types and typed showGenres arrays.

#### 2026-07-06

- ✨ README overhaul: full per-mode field reference, richer output sample, ready-to-run example scenarios (catalogue / episodes / schedule), media & entertainment cross-promo links, expanded FAQ and clearer quick-start.

#### 2026-07-01

- Initial release: seven TVMaze modes (show index, search shows, show details, episodes, cast, schedule, people) over the open TVMaze REST API — no key, no browser.

# Actor input Schema

## `mode` (type: `string`):

Which TVMaze endpoint to run.

• **showIndex** — the full TVMaze catalogue, 250 shows per page, paginated (highest volume — default)
• **searchShows** — free-text search for TV shows by name
• **showDetails** — full details for one or more show IDs (batch), optional cast embed
• **episodes** — every episode of a series (a long-running show returns hundreds)
• **cast** — cast members and the characters they play, for a show
• **schedule** — a full day of TV airings for a country (100+ across the US)
• **people** — free-text people search, or details for one/more person IDs

## `query` (type: `string`):

Free-text term for **searchShows** (a show name) or **people** (a person name).

## `showId` (type: `string`):

TVMaze show ID (a plain integer), e.g. `169` (Breaking Bad) or `83` (The Simpsons). Used by **showDetails**, **episodes**, **cast**. It is the number in a TVMaze show URL: tvmaze.com/shows/**169**/…

## `showIds` (type: `array`):

Array of TVMaze show IDs (integers) for batch **showDetails**.

## `embedCast` (type: `boolean`):

When true, **showDetails** also attaches a compact `cast[]` list (actor + character) to each show via `?embed[]=cast`.

## `personId` (type: `string`):

TVMaze person ID (an integer), e.g. `1`. Used by **people** mode. It is the number in a TVMaze person URL: tvmaze.com/people/**1**/…

## `personIds` (type: `array`):

Array of TVMaze person IDs (integers) for batch **people** lookups.

## `country` (type: `string`):

ISO 3166-1 alpha-2 country code for **schedule** mode. A full US day returns 100+ airings; large TV markets (US, GB, CA, AU) return the most.

## `date` (type: `string`):

Day to pull the **schedule** for, format `YYYY-MM-DD`. Leave empty for today.

## `startPage` (type: `integer`):

Page number to start the **showIndex** pagination from (0-based). Each page is 250 shows. Use it to resume or skip ahead through the catalogue.

## `maxResults` (type: `integer`):

Upper bound on rows returned. For showIndex this drives pagination through the catalogue; for other modes it caps the returned list.

## Actor input object example

```json
{
  "mode": "showIndex",
  "query": "breaking bad",
  "showId": "169",
  "showIds": [
    "169",
    "82",
    "83"
  ],
  "embedCast": false,
  "personId": "1",
  "personIds": [],
  "country": "US",
  "date": "2024-01-10",
  "startPage": 0,
  "maxResults": 250
}
```

# Actor output Schema

## `results` (type: `string`):

Full results dataset. Use the Shows view for show/search modes, Episodes for episode lists, Cast for cast, Schedule for daily airings, and People for person lookups.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "showIndex",
    "showIds": [
        "169",
        "82",
        "83"
    ],
    "country": "US",
    "maxResults": 250
};

// Run the Actor and wait for it to finish
const run = await client.actor("logiover/tvmaze-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "showIndex",
    "showIds": [
        "169",
        "82",
        "83",
    ],
    "country": "US",
    "maxResults": 250,
}

# Run the Actor and wait for it to finish
run = client.actor("logiover/tvmaze-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "showIndex",
  "showIds": [
    "169",
    "82",
    "83"
  ],
  "country": "US",
  "maxResults": 250
}' |
apify call logiover/tvmaze-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=logiover/tvmaze-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/m3cU4eAlWraEhXz7Y/builds/1kdF3Q4bdZUezwxy7/openapi.json