# TV Show Scraper — Episodes, Cast & Ratings (TVMaze) (`eins332570/tv-show-scraper`) Actor

Scrape TV show data — episodes, cast, genres, networks, air dates, and ratings — from the TVMaze public API into one unified dataset. Search by show name or look up by TVMaze or IMDb ID. Great for media catalogs, recommendations, and entertainment analytics. No login, no API key, no proxy.

- **URL**: https://apify.com/eins332570/tv-show-scraper.md
- **Developed by:** [thanachit singruang](https://apify.com/eins332570) (community)
- **Categories:** Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 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.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## TV Show Scraper — Episodes, Cast & Ratings (TVMaze)

Scrape **TV shows**, their **episodes**, and **cast** into **one unified dataset** — using the free, public **TVMaze API**. No login, no proxies, no browser. Just clean, structured TV data.

Search by show name, or look up specific shows by **TVMaze ID** or **IMDb ID**, then optionally pull every episode and the full cast.

### What you get

**Show rows** (`recordType: "show"`):

| Field | Description |
|---|---|
| `showId` | TVMaze show ID |
| `name` | show title |
| `type` | Scripted / Reality / Animation, etc. |
| `language` | primary language |
| `genres` | list of genres |
| `status` | Running / Ended / To Be Determined |
| `runtime` | typical episode runtime (minutes) |
| `premiered` / `ended` | ISO dates |
| `rating` | average user rating (0–10) |
| `network` | broadcast network or streaming channel |
| `country` | network country code |
| `imdbId` / `tvdbId` | external IDs |
| `officialSite` / `url` | official site + TVMaze page |
| `image` | poster image |
| `summary` | plain-text synopsis |
| `updatedAt` | ISO timestamp of the last TVMaze update |

**Episode rows** (`recordType: "episode"`, when **Include episodes** is on): `episodeId`, `showId`, `showName`, `season`, `number`, `name`, `airdate`, `runtime`, `rating`, `url`, `summary`.

**Cast rows** (`recordType: "castMember"`, when **Include cast** is on): `showId`, `showName`, `person`, `character`, `personId`, `characterId`, `self`, `voice`, `url`, `image`.

### Input

```json
{
  "search": ["breaking bad"],
  "showIds": ["169"],
  "imdbIds": ["tt0903747"],
  "includeEpisodes": false,
  "includeCast": false
}
```

- **search** — show names to search on TVMaze.
- **showIds** — TVMaze IDs (the number in `tvmaze.com/shows/<id>`).
- **imdbIds** — IMDb IDs, e.g. `tt0903747`.
- **includeEpisodes** — also fetch every episode of each show.
- **includeCast** — also fetch the cast of each show.

Provide at least one of `search`, `showIds`, or `imdbIds`. Shows found across multiple sources are de-duplicated by TVMaze ID.

### Sample output

One dataset row (a show; episode and cast rows are added when those options are on):

```json
{
  "recordType": "show",
  "showId": "526",
  "name": "The Office",
  "type": "Scripted",
  "language": "English",
  "genres": ["Comedy"],
  "status": "Ended",
  "runtime": 30,
  "premiered": "2005-03-24T00:00:00.000Z",
  "ended": "2013-05-16T00:00:00.000Z",
  "rating": 8.5,
  "network": "NBC",
  "country": "US",
  "imdbId": "tt0386676",
  "tvdbId": "73244",
  "officialSite": "http://www.nbc.com/the-office",
  "url": "https://www.tvmaze.com/shows/526/the-office",
  "image": "https://static.tvmaze.com/uploads/images/original_untouched/481/1204342.jpg",
  "summary": "Steve Carell stars in The Office, a mockumentary-style glimpse into the daily interactions of the workers at Dunder Mifflin…",
  "updatedAt": "2026-05-12T21:37:54.000Z"
}
```

### Why it's reliable & cheap

Every request hits the **public TVMaze JSON API** — no headless browser, no anti-bot walls, no API key. Transient errors (rate limits, 5xx, network blips) are retried automatically, and an unreachable or unknown source is reported and skipped — one bad source never fails the whole run.

### Use cases

- **Media & entertainment datasets** — build a catalog of shows, ratings, and air dates
- **Recommendation & discovery** — genres, cast overlap, network line-ups
- **Research & analytics** — ratings trends, episode counts, network comparisons
- **Enriching an IMDb/TVDB pipeline** — resolve shows across external IDs

Data courtesy of the [TVMaze API](https://www.tvmaze.com/api) (licensed CC BY-SA).

### FAQ

**Do I need an API key or login?** No. It uses the free, public TVMaze API — no key, no account, no proxy.

**Is it free to try?** Yes — click **Try for free** and run the prefilled search (`breaking bad`) in seconds.

**How do I get episodes and cast?** Turn on **Include episodes** and **Include cast** — both come from a single request per show.

**Can I look up a show by IMDb ID?** Yes — pass `imdbIds` (e.g. `tt0903747`) or TVMaze `showIds`.

**Is this allowed?** TVMaze offers a public API for exactly this; its data is licensed CC BY-SA (attribution included in the output docs).

### Pricing

**Pay per result — $5 per 1,000 shows.** Episodes and cast are included with each show at no extra charge. Runs that return nothing cost nothing.

# Actor input Schema

## `search` (type: `array`):

Search TVMaze by show name. Each query returns the matching shows. Example: \["breaking bad", "the office"].

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

Fetch specific shows by their TVMaze ID (the number in the tvmaze.com/shows/<id> URL, e.g. 169 for Breaking Bad).

## `imdbIds` (type: `array`):

Look up shows by their IMDb ID, e.g. "tt0903747".

## `includeEpisodes` (type: `boolean`):

Also fetch every episode of each show (adds episode rows to the dataset).

## `includeCast` (type: `boolean`):

Also fetch the cast of each show (adds cast-member rows to the dataset).

## Actor input object example

```json
{
  "search": [
    "breaking bad"
  ],
  "includeEpisodes": false,
  "includeCast": false
}
```

# Actor output Schema

## `items` (type: `string`):

All scraped records as dataset items.

# 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 = {
    "search": [
        "breaking bad"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("eins332570/tv-show-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 = { "search": ["breaking bad"] }

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

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

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

```

## CLI example

```bash
echo '{
  "search": [
    "breaking bad"
  ]
}' |
apify call eins332570/tv-show-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,eins332570/tv-show-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/O0KXR9o9AhoXptAXQ/builds/JRwYjEHQu6HngbEuS/openapi.json