# TVmaze TV Show & Episode Scraper (`crawlerbros/tvmaze-scraper`) Actor Search and scrape TV show data from TVmaze - ratings, episodes, cast, schedules, and more for 50,000+ shows worldwide. No API key required. - **URL**: https://apify.com/crawlerbros/tvmaze-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Developer tools, Integrations - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 TV Show & Episode Scraper Extract comprehensive TV show data from **TVmaze** — ratings, episodes, cast, schedules, and more for **50,000+ shows** worldwide. No API key or authentication required. ### What it does Scrapes the TVmaze public REST API to collect detailed TV show metadata across 5 modes: search, browse, episode lists, TV schedules, and cast/people data. ### Input | Field | Type | Description | Default | |-------|------|-------------|---------| | `mode` | string | What to scrape (see modes below) | `searchShows` | | `query` | string | Show title or keyword (mode=searchShows) | `breaking bad` | | `showId` | integer | TVmaze show ID for episode mode | — | | `scheduleDate` | string | Date for schedule in YYYY-MM-DD format | today | | `scheduleCountry` | string | Country code for broadcast schedule (US, GB, AU, etc.) | `US` | | `genreFilter` | string | Filter by genre in browse mode | all | | `statusFilter` | string | Filter by airing status (Running, Ended, etc.) | all | | `maxItems` | integer | Maximum records to emit (1–5,000) | 50 | #### Modes | Mode | Description | |------|-------------| | `searchShows` | Search TV shows by name or keyword | | `browseShows` | Browse all shows with optional genre/status filtering | | `episodes` | Get all episodes for a specific show (provide `showId`) | | `schedule` | Tonight's TV schedule — both streaming and broadcast | | `people` | Browse actors and directors | ### Output #### Show record ```json { "id": 169, "url": "https://www.tvmaze.com/shows/169/breaking-bad", "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, "networkName": "AMC", "networkCountry": "US", "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/81/202627.jpg", "imageOriginal": "https://static.tvmaze.com/uploads/images/original_untouched/81/202627.jpg", "summary": "Breaking Bad is an American crime drama television series.", "imdbId": "tt0903747", "thetvdbId": 81189, "officialSite": "http://www.amc.com/shows/breaking-bad", "recordType": "show", "scrapedAt": "2024-01-15T14:30:00+00:00" } ```` #### Episode record ```json { "episodeId": 4952, "showId": 82, "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming", "name": "Winter is Coming", "season": 1, "episodeNumber": 1, "type": "regular", "airdate": "2011-04-17", "airtime": "21:00", "airstamp": "2011-04-18T01:00:00+00:00", "runtime": 60, "rating": 8.2, "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/...", "summary": "Jon Snow is given a harsh lesson in survival.", "recordType": "episode", "scrapedAt": "2024-01-15T14:30:00+00:00" } ``` #### Person record ```json { "id": 1, "url": "https://www.tvmaze.com/people/1/mike-vogel", "name": "Mike Vogel", "gender": "Male", "birthday": "1979-07-17", "country": "United States", "countryCode": "US", "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/0/1.jpg", "recordType": "person", "scrapedAt": "2024-01-15T14:30:00+00:00" } ``` #### Output Fields | Field | Type | Description | |-------|------|-------------| | `id` / `episodeId` | integer | TVmaze unique identifier | | `url` | string | TVmaze page URL | | `name` | string | Show or episode title | | `type` | string | Show type (Scripted, Reality, Animation, etc.) | | `language` | string | Primary language | | `genres` | array | Genre tags | | `status` | string | Airing status (Running, Ended, etc.) | | `runtime` | integer | Episode runtime in minutes | | `premiered` | string | Premiere date (YYYY-MM-DD) | | `ended` | string | End date if concluded | | `rating` | number | Average user rating (0–10) | | `networkName` | string | Broadcast network | | `networkCountry` | string | Network country code | | `webChannel` | string | Streaming platform (Netflix, Hulu, etc.) | | `imageMedium` | string | Medium poster/image URL | | `imageOriginal` | string | Full-size poster/image URL | | `summary` | string | Plain-text description (HTML removed) | | `imdbId` | string | IMDb cross-reference ID | | `thetvdbId` | integer | TheTVDB cross-reference ID | | `recordType` | string | `show`, `episode`, `person`, or `schedule` | | `scrapedAt` | string | ISO 8601 UTC scrape timestamp | All fields are omit-empty — null or empty fields are not included in output. ### Use Cases - **TV recommendation systems** — Build a show database with genres, ratings, and metadata. - **Episode trackers** — Get full episode lists with air dates, numbers, and synopses. - **Streaming research** — Identify which shows air on which networks and platforms. - **Content calendars** — Pull today's TV schedule to see what's on. - **Show database enrichment** — Use IMDb and TheTVDB IDs for cross-referencing. - **Cast research** — Build a directory of TV actors with biographical data. ### Example Inputs #### Search for a show ```json { "mode": "searchShows", "query": "the wire", "maxItems": 10 } ``` #### Browse all drama shows currently running ```json { "mode": "browseShows", "genreFilter": "Drama", "statusFilter": "Running", "maxItems": 100 } ``` #### Get all episodes of Breaking Bad (show ID 169) ```json { "mode": "episodes", "showId": 169, "maxItems": 100 } ``` #### Tonight's US schedule ```json { "mode": "schedule", "scheduleCountry": "US", "maxItems": 100 } ``` #### Browse actors ```json { "mode": "people", "maxItems": 200 } ``` ### Data Source Data is sourced from the **TVmaze REST API** (`api.tvmaze.com`), a free public API covering 50,000+ TV shows worldwide. The API requires no authentication for basic public access (rate limit: 20 calls/10 seconds for anonymous users). ### FAQs **Do I need an API key?** No. TVmaze's public REST API is free and requires no authentication for basic data access. **How do I find a show's ID?** Run in `searchShows` mode — the `id` field in results is the TVmaze show ID to use in `episodes` mode. **Can I get show images?** Yes. Both `imageMedium` (210×295 px) and `imageOriginal` (full resolution) URLs are included for shows, episodes, and people. **Why might some shows not have ratings?** Shows without enough user ratings on TVmaze will not have a rating field in the output (the actor omits empty/zero values). **What's the difference between streaming and broadcast schedules?** In `schedule` mode, the actor fetches both the web/streaming schedule (Netflix, Hulu, Amazon, etc.) and the traditional broadcast schedule for the selected country. **Are episode summaries plain text?** Yes. The actor automatically strips HTML tags from summaries, so the output is always clean plain text. # Actor input Schema ## `mode` (type: `string`): What to scrape from TVmaze. ## `query` (type: `string`): TV show title or keyword to search for. ## `showId` (type: `integer`): TVmaze show ID to fetch episodes for. Find IDs via searchShows or browseShows mode. ## `scheduleDate` (type: `string`): Date for TV schedule in YYYY-MM-DD format. Leave empty for today. ## `scheduleCountry` (type: `string`): Country code for TV schedule (e.g. US, GB, AU, DE, FR). ## `genreFilter` (type: `string`): Filter shows by genre (e.g. Drama, Comedy, Thriller). ## `statusFilter` (type: `string`): Filter shows by airing status. ## `maxItems` (type: `integer`): Maximum number of records to emit. ## Actor input object example ```json { "mode": "searchShows", "query": "breaking bad", "scheduleCountry": "US", "genreFilter": "", "statusFilter": "", "maxItems": 50 } ``` # Actor output Schema ## `shows` (type: `string`): Dataset containing all scraped TVmaze records. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "searchShows", "query": "breaking bad", "scheduleCountry": "US", "genreFilter": "", "statusFilter": "", "maxItems": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "searchShows", "query": "breaking bad", "scheduleCountry": "US", "genreFilter": "", "statusFilter": "", "maxItems": 50, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/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": "searchShows", "query": "breaking bad", "scheduleCountry": "US", "genreFilter": "", "statusFilter": "", "maxItems": 50 }' | apify call crawlerbros/tvmaze-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/tvmaze-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TVmaze TV Show & Episode Scraper", "description": "Search and scrape TV show data from TVmaze - ratings, episodes, cast, schedules, and more for 50,000+ shows worldwide. No API key required.", "version": "1.0", "x-build-id": "uUezLRNWAFbmB6xyU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~tvmaze-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-tvmaze-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~tvmaze-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-tvmaze-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~tvmaze-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-tvmaze-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "searchShows", "browseShows", "episodes", "schedule", "people" ], "type": "string", "description": "What to scrape from TVmaze.", "default": "searchShows" }, "query": { "title": "Search query (mode=searchShows)", "type": "string", "description": "TV show title or keyword to search for." }, "showId": { "title": "Show ID (mode=episodes)", "minimum": 1, "type": "integer", "description": "TVmaze show ID to fetch episodes for. Find IDs via searchShows or browseShows mode." }, "scheduleDate": { "title": "Schedule date (mode=schedule)", "type": "string", "description": "Date for TV schedule in YYYY-MM-DD format. Leave empty for today." }, "scheduleCountry": { "title": "Schedule country (mode=schedule)", "enum": [ "US", "GB", "AU", "DE", "FR", "CA", "NL", "JP", "IT", "ES", "BR" ], "type": "string", "description": "Country code for TV schedule (e.g. US, GB, AU, DE, FR).", "default": "US" }, "genreFilter": { "title": "Genre filter (mode=browseShows)", "enum": [ "", "Drama", "Comedy", "Crime", "Action", "Thriller", "Science-Fiction", "Horror", "Romance", "Adventure", "Fantasy", "Anime", "Family", "Children", "Documentary", "News", "Sports", "Reality", "Game Show", "Talk Show" ], "type": "string", "description": "Filter shows by genre (e.g. Drama, Comedy, Thriller).", "default": "" }, "statusFilter": { "title": "Status filter (mode=browseShows)", "enum": [ "", "Running", "Ended", "To Be Determined", "In Development" ], "type": "string", "description": "Filter shows by airing status.", "default": "" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of records to emit.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```