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

Search TV shows and get genres, network, rating, premiere/end dates, runtime, IMDb ID, official site, summary and poster, plus optional episode list and cast. Powered by TVMaze. Keyless, no anti-bot.

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

## Pricing

from $2.75 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TVMaze Scraper — TV Shows, Episodes & Cast

Search **TV shows** and get rich metadata — genres, network, rating, premiere/end dates, runtime, **IMDb ID**, official site, summary and poster — plus optional **episode list** (count, seasons, latest) and **cast** (actor → character). Clean JSON/CSV/Excel.

Powered by **TVMaze**. **Keyless**, no anti-bot — built for TV/streaming apps, guides, trackers and entertainment datasets.

***

### What this Actor does

Give it show searches and for each matching show it returns:

- **Core** — name, type (Scripted/Reality…), language, genres, status (Running/Ended), runtime.
- **Dates & rating** — premiere and end dates, average rating.
- **Network** — network or web channel (Netflix, HBO…) and its country.
- **IDs & links** — IMDb ID, TheTVDB ID, official site, TVMaze page and poster image.
- **Summary** — clean plain-text synopsis.
- **Optional** — episode summary (count, seasons, latest episode) and the main cast.

***

### Why use it

- **A free, clean TV API.** Structured show metadata without a key or anti-bot — a solid alternative to scraping IMDb.
- **Cross-reference with IMDb.** Every show carries its IMDb ID for easy joins.
- **Episodes & cast on demand.** Flip on episodes and cast to enrich each show.
- **Great for apps & content.** Streaming guides, trackers, recommendation engines, fan sites and datasets.
- **Networks & web channels.** Covers traditional networks and streamers alike.

***

### Who it's for

- **TV / streaming app developers** needing show, episode and cast data.
- **Content & entertainment teams** building guides and trackers.
- **Data & recommendation builders** assembling TV datasets.
- **Fan sites & bots** surfacing show info and cast.

***

### Quick start

#### Run it in the console (no code)

1. In **Show searches**, add one per line:

   ```
   breaking bad
   the office
   game of thrones
   ```

2. *(Optional)* turn on **Include episodes summary** and/or **Include cast**.

3. Click **Start**, then export as **JSON, CSV, Excel or HTML**.

Leave queries empty for a **demo**.

#### Run it via API (Python)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run_input = {
    "queries": ["breaking bad", "the wire"],
    "includeEpisodes": True,
    "includeCast": True,
}

run = client.actor("YOUR_USERNAME/tvmaze-scraper").call(run_input=run_input)

for s in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{s['name']} ({s['premiered'][:4]}) — {s['rating']} — {s['network']} — {s['episodeCount']} eps")
```

#### Run it via API (JavaScript)

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

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

const run = await client.actor('YOUR_USERNAME/tvmaze-scraper').call({
    queries: ['breaking bad'],
    includeCast: true,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((s) => console.log(`${s.name}: ${s.genres} — ${s.cast}`));
```

***

### Input

| Field | Type | Description |
|---|---|---|
| **Show searches** | array | One show search per line. Empty = demo. |
| **Include episodes summary** | boolean | Add episode count, season count and latest episode. |
| **Include cast** | boolean | Add main cast (actor → character). |
| **Max shows per query** | integer | Matching shows to keep per search. Default 50. |
| **Speed (parallel queries)** | integer | Searches at once. Default 5. |
| **Proxy configuration** | object | Apify Proxy. On by default. |

***

### Output

One record per show:

```json
{
  "query": "breaking bad",
  "showId": "169",
  "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",
  "network": "AMC",
  "networkCountry": "United States",
  "officialSite": "http://www.amc.com/shows/breaking-bad",
  "imdbId": "tt0903747",
  "summary": "Breaking Bad follows protagonist Walter White...",
  "image": "https://static.tvmaze.com/uploads/images/original_untouched/0/2400.jpg",
  "url": "https://www.tvmaze.com/shows/169/breaking-bad",
  "episodeCount": "62",
  "seasonCount": "5",
  "latestEpisode": "Felina (S5E16, 2013-09-29)",
  "cast": "Bryan Cranston as Walter White; Aaron Paul as Jesse Pinkman; ...",
  "castCount": "11",
  "scrapedAt": "2026-10-10T12:00:00.000Z"
}
```

| Field | Description |
|---|---|
| `name` / `type` / `language` / `genres` | Core show info. |
| `status` / `runtime` / `premiered` / `ended` | Status, runtime and dates. |
| `rating` | TVMaze average rating. |
| `network` / `networkCountry` | Network or web channel and country. |
| `imdbId` / `thetvdbId` / `officialSite` / `url` | External IDs and links. |
| `summary` / `image` | Synopsis and poster. |
| `episodeCount` / `seasonCount` / `latestEpisode` | With **Include episodes**. |
| `cast` / `castCount` | With **Include cast**. |
| `scrapedAt` | ISO timestamp. |

***

### Tips & notes

- **Search returns matches.** A query like `breaking` returns several shows — raise/lower *Max shows per query* to control how many.
- **Join on IMDb.** Use `imdbId` to merge with IMDb-based datasets.
- **Episodes/cast cost extra calls.** They're off by default; turn on only what you need.
- **Networks vs web channels.** Streamers (Netflix, HBO Max…) appear in `network` too.
- **Ratings vary.** Popular shows have ratings; obscure ones may not.

***

### Frequently asked questions

**Do I need an API key?**
No — TVMaze's API is public and keyless.

**Can I get episodes and cast?**
Yes — enable **Include episodes summary** and **Include cast**.

**Is there an IMDb link?**
Yes — every show carries its IMDb ID.

**Does it cover streaming shows?**
Yes — network and web-channel shows (Netflix, HBO, etc.) are included.

**Good for a TV app or recommender?**
Yes — clean, structured show/episode/cast data is ideal for apps, guides and recommendation engines.

***

### Export & integrate

Results are available as **JSON, CSV, Excel, HTML** and via the **Apify API**. Push to **Google Sheets**, a **webhook**, **Make**, **Zapier** or your database.

*Data from TVMaze.*

# Actor input Schema

## `queries` (type: `array`):

One TV show search per line — e.g. `breaking bad`, `the office`, `game of thrones`. Each returns the matching shows with full metadata. Leave empty for a demo.

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

Add episode count, season count and the latest episode for each show.

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

Add the main cast (actor → character) for each show.

## `maxItemsPerQuery` (type: `integer`):

How many matching shows to keep per search.

## `maxConcurrency` (type: `integer`):

How many searches at once. TVMaze rate-limits — keep modest.

## `proxyConfiguration` (type: `object`):

Apify Proxy. On by default.

## Actor input object example

```json
{
  "queries": [
    "breaking bad",
    "the office"
  ],
  "includeEpisodes": false,
  "includeCast": false,
  "maxItemsPerQuery": 50,
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Search query

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

TVMaze show ID

## `name` (type: `string`):

Show name

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

Scripted/Reality…

## `language` (type: `string`):

Language

## `genres` (type: `string`):

Genres

## `status` (type: `string`):

Running/Ended

## `runtime` (type: `string`):

Runtime (min)

## `premiered` (type: `string`):

Premiere date

## `ended` (type: `string`):

End date

## `rating` (type: `string`):

Average rating

## `network` (type: `string`):

Network/web channel

## `networkCountry` (type: `string`):

Network country

## `officialSite` (type: `string`):

Official site

## `imdbId` (type: `string`):

IMDb ID

## `summary` (type: `string`):

Summary

## `image` (type: `string`):

Poster URL

## `url` (type: `string`):

TVMaze page

## `episodeCount` (type: `string`):

Episode count

## `seasonCount` (type: `string`):

Season count

## `latestEpisode` (type: `string`):

Latest episode

## `cast` (type: `string`):

Cast (actor as character)

## `castCount` (type: `string`):

Cast count

## `scrapedAt` (type: `string`):

Timestamp

# 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 = {
    "queries": [
        "breaking bad",
        "the office"
    ],
    "maxItemsPerQuery": 50,
    "maxConcurrency": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("haketa/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 = {
    "queries": [
        "breaking bad",
        "the office",
    ],
    "maxItemsPerQuery": 50,
    "maxConcurrency": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("haketa/tvmaze-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 '{
  "queries": [
    "breaking bad",
    "the office"
  ],
  "maxItemsPerQuery": 50,
  "maxConcurrency": 5
}' |
apify call haketa/tvmaze-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,haketa/tvmaze-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/jO65ZXuazxf5cSDWW/builds/eKPISdNxk3Vevnpsj/openapi.json