TVmaze Scraper · TV Shows, Episodes, Casts & Networks

Scrape TV shows, episode listings, cast lists, television networks, streaming channels, user ratings, genres, and broadcast schedules from TVmaze's public REST database. Extract clean, structured JSON dataset records for television series analytics, streaming market research, content discovery, media monitoring, and metadata integration.

Maintained by reapX. Every row cites the Apify run that produced it — nothing is inferred, modelled or filled in, and a field absent from the source is absent from the row. The extracted archive for this source is browsable at reapx.dev/data/tvmaze-scraper/ and mirrored as an open dataset on Hugging Face and Kaggle. Questions: reapxdev@proton.me

---

Features

• Comprehensive Show Metadata: Scrape full show titles, slugs, production status, genres, episode runtimes, broadcast languages, official websites, and summary descriptions.
• Network & Web Channels: Extract broadcast television networks (CBS, NBC, HBO, BBC, FOX, AMC, ABC, Showtime, FX, CW) and web streaming channels (Netflix, Amazon Prime Video, Hulu, Apple TV+, Disney+).
• Ratings & Popularity: Capture average user rating scores out of 10, vote weights, and popularity metrics across thousands of global television series.
• External Identifiers: Retrieve linked IMDb IDs (imdbId), TheTVDB IDs (thetvdbId), and TVRage IDs (tvrageId) for seamless cross-platform dataset joining.
• Flexible Search & Filtering: Filter television series by search query terms, primary genres, network names, production status, origin countries, or minimum user rating thresholds.
• Pay-Per-Event Billing: Pay only for complete show records successfully returned and pushed to your default dataset. Failed or empty requests incur zero charge.

---

⬇️ Input

The TVmaze Scraper accepts flexible JSON input parameters to control data scope, search keywords, network filters, and show extraction limits.

Parameter	Type	Default	Description
searchQuery	String	""	Search query string to match against show names and titles (e.g. drama, star, game). Leave empty for main index pagination.
genre	String	""	Filter shows by primary genre tag (e.g. Drama, Comedy, Science-Fiction, Thriller, Action, Crime, Anime).
network	String	""	Filter by broadcasting network or streaming web channel name (e.g. CBS, HBO, Netflix, BBC One, NBC).
country	String	""	Filter shows by network country of origin (e.g. United States, United Kingdom, Japan, Canada, France).
status	String	""	Filter shows by current production status (Running, Ended, To Be Determined, In Development).
minRating	Number	null	Minimum average user rating score from 0.0 to 10.0 (e.g. 7.5, 8.0, 8.5).
startPage	Integer	0	Starting page index for sequential database pagination (0 to 1000).
maxShows	Integer	50	Maximum number of TV show records to extract and output (1 to 5000).

Input JSON Configurations

Example 1: Extracting Popular Sci-Fi Series from Netflix

{
  "network": "Netflix",
  "genre": "Science-Fiction",
  "minRating": 7.5,
  "maxShows": 50
}

Example 2: Searching TV Shows by Keyword

{
  "searchQuery": "star",
  "minRating": 7.0,
  "maxShows": 25
}

Example 3: Sequential Pagination of Active Drama Series

{
  "genre": "Drama",
  "status": "Running",
  "startPage": 0,
  "maxShows": 100
}

---

⬆️ Output

All extracted television show records are pushed incrementally into the run's default dataset. Output data is formatted in standard camelCase JSON objects.

Dataset Schema Fields

Field Name	Type	Description	Example
slug	String	URL slug identifier of the show on TVmaze	"under-the-dome"
showId	Integer	Numeric TVmaze ID of the show	1
name	String	Official title name of the TV show	"Under the Dome"
type	String	Type of TV show (Scripted, Reality, Animation)	"Scripted"
language	String	Primary language spoken in the show	"English"
genres	Array	List of genre tags assigned to the show	["Drama", "Science-Fiction", "Thriller"]
status	String	Current production status of the series	"Ended"
runtime	Integer	Standard episode runtime duration in minutes	60
averageRuntime	Integer	Average runtime across all episodes	60
premiered	String	Date the series first premiered (YYYY-MM-DD)	"2013-06-24"
ended	String	Date the series ended or concluded (YYYY-MM-DD)	"2015-09-10"
officialSite	String	Official website URL of the show	"http://www.cbs.com/shows/under-the-dome/"
scheduleTime	String	Time of day the show airs	"22:00"
scheduleDays	Array	Days of the week the show airs	["Thursday"]
ratingAverage	Number	Average TVmaze user rating score out of 10	6.6
weight	Integer	TVmaze popularity weight score	99
networkName	String	Name of the broadcasting network	"CBS"
networkCountry	String	Country name of the broadcasting network	"United States"
networkCode	String	2-letter ISO country code of the network	"US"
networkTimezone	String	Timezone of the primary network broadcast	"America/New_York"
webChannelName	String	Name of the streaming service or web channel	"Netflix"
imdbId	String	IMDb identifier string	"tt1553656"
thetvdbId	Integer	TheTVDB numeric show identifier	264492
tvrageId	Integer	TVRage numeric show identifier	25988
imageMedium	String	URL of medium-sized poster image	"https://static.tvmaze.com/uploads/images/medium_portrait/610/1525272.jpg"
imageOriginal	String	URL of original untouched poster image	"https://static.tvmaze.com/uploads/images/original_untouched/610/1525272.jpg"
summaryText	String	Plain text summary description of the show	"Under the Dome is the story of a small town..."
summaryHtml	String	Raw HTML summary string from TVmaze	"<p><b>Under the Dome</b> is the story...</p>"
updatedAt	Integer	Unix timestamp of when show record was updated	1769177765
url	String	Canonical URL of the show on TVmaze	"https://www.tvmaze.com/shows/1/under-the-dome"

Sample Output Record

{
  "slug": "under-the-dome",
  "showId": 1,
  "name": "Under the Dome",
  "type": "Scripted",
  "language": "English",
  "genres": [
    "Drama",
    "Science-Fiction",
    "Thriller"
  ],
  "status": "Ended",
  "runtime": 60,
  "averageRuntime": 60,
  "premiered": "2013-06-24",
  "ended": "2015-09-10",
  "officialSite": "http://www.cbs.com/shows/under-the-dome/",
  "scheduleTime": "22:00",
  "scheduleDays": [
    "Thursday"
  ],
  "ratingAverage": 6.6,
  "weight": 99,
  "networkName": "CBS",
  "networkCountry": "United States",
  "networkCode": "US",
  "networkTimezone": "America/New_York",
  "webChannelName": null,
  "imdbId": "tt1553656",
  "thetvdbId": 264492,
  "tvrageId": 25988,
  "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/610/1525272.jpg",
  "imageOriginal": "https://static.tvmaze.com/uploads/images/original_untouched/610/1525272.jpg",
  "summaryText": "Under the Dome is the story of a small town that is suddenly and inexplicably sealed off from the rest of the world by an enormous transparent dome.",
  "summaryHtml": "<p><b>Under the Dome</b> is the story of a small town that is suddenly and inexplicably sealed off from the rest of the world by an enormous transparent dome.</p>",
  "updatedAt": 1769177765,
  "url": "https://www.tvmaze.com/shows/1/under-the-dome"
}

---

How it works

The TVmaze Scraper operates by interfacing directly with the public TVmaze REST API (api.tvmaze.com).

1. Input Normalization: The scraper parses specified input configuration parameters including search terms, network names, genre filters, and rating boundaries.
2. Endpoint Selection:
   • If searchQuery is provided, the actor calls https://api.tvmaze.com/search/shows?q={searchQuery} to fetch query matches.
   • If searchQuery is omitted, the actor queries sequential index pages via https://api.tvmaze.com/shows?page={startPage}.
3. Filtering & Transformation: Each returned show record is normalized into clean camelCase fields. slug is extracted directly from the show URL path to ensure stable entity-page resolution.
4. Pay-Per-Event Charging: For each validated show record written to the dataset, the actor triggers a show-returned pay-per-event charge. Failed requests or empty filter responses incur zero cost.
5. Incremental Dataset Storage: Records are pushed immediately to the run's default dataset (Actor.push_data) as they are parsed, avoiding memory buffering issues.

---

Pricing & Pay-Per-Event

This actor uses Pay-Per-Event (PPE) pricing. You pay only for successfully extracted show records written to your default dataset.

• Primary Event: show-returned ($0.002 USD per show record)
• Tiered Volume Discounts:
  • FREE Tier: $0.0020 / record
  • BRONZE Tier: $0.0018 / record
  • SILVER Tier: $0.0015 / record
  • GOLD Tier: $0.0013 / record
  • PLATINUM Tier: $0.0010 / record
  • DIAMOND Tier: $0.0008 / record

Platform execution compute costs are absorbed into event pricing. Empty search results or HTTP error retries are never charged.

---

Data Quality & Entity Page Integrity

Every record emitted by this scraper is keyed by slug, derived directly from the canonical TVmaze URL. This ensures that:

• Every show row has a unique, deterministic, non-constant entity key.
• Downstream entity page generators (growth/entity_pages.py) can resolve and index distinct show data pages cleanly.
• showId is preserved as a numeric attribute without replacing slug as the primary addressable key.

---

Use Cases

• Entertainment Market Intelligence: Analyze television production trends across networks, streaming providers, and international markets.
• Media Catalog Enrichment: Cross-reference movie and TV show databases using IMDb, TheTVDB, and TVRage identifiers.
• Streaming & Broadcast Monitoring: Track currently active television series schedules, runtime durations, and broadcast days.
• Content Recommendation Engines: Build content similarity systems based on user rating averages, genre combinations, and plot summaries.

---

❓ FAQ

1. What happens if a show has no network (e.g. web streaming series)?

Web-only series (such as Netflix, Hulu, or Amazon Prime Video originals) return webChannelName populated while networkName may be null. The scraper normalizes both fields so network filtering matches against either traditional broadcast networks or digital streaming platforms.

2. How is the show slug generated?

The slug field is extracted directly from the show's canonical TVmaze URL (e.g. https://www.tvmaze.com/shows/1/under-the-dome -> under-the-dome). This ensures that every row carries a unique, human-readable, and stable entity identifier.

3. Can I filter shows by rating?

Yes! Set minRating to a number between 0.0 and 10.0 (for example 8.0). Shows with average user ratings below this threshold will be excluded client-side before dataset insertion.

4. What is the maximum number of shows I can scrape in a single run?

You can extract up to 5,000 shows per run by setting maxShows. For larger batch extractions, you can chain multiple runs using the startPage pagination index parameter.

5. How are external database IDs stored?

External IDs (imdbId, thetvdbId, tvrageId) are parsed directly from TVmaze's externals object and exported as top-level dataset fields for easy joining with external datasets.

6. Are there rate limits on the TVmaze API?

TVmaze allows reasonable public API access. The scraper includes automatic exponential backoff on HTTP 429 and 5xx status codes to maintain respectful crawling speeds and ensure high run reliability.

---

💬 Your feedback

We actively maintain our scrapers and welcome user feature requests, bug reports, and dataset suggestions.

• Issue Reporting & Support: Contact us directly at reapxdev@proton.me
• Data Archive & Datasets: Access pre-built archive dumps at reapx.dev/data/tvmaze-scraper/
• Hugging Face Datasets: huggingface.co/datasets/reapxdev/tvmaze-scraper
• Kaggle Datasets: kaggle.com/datasets/reapxdev/tvmaze-scraper

---

Unofficial - not affiliated with TVmaze. Collects public data only. reapx. Contact reapxdev@proton.me.

🧪 Example input

A real, runnable configuration — this is an actual input this Actor has run with.

{
  "genre": "Drama",
  "maxShows": 50
}

📄 Sample output

One real row from a real run of this Actor, unedited.

{
  "slug": "under-the-dome",
  "showId": 1,
  "name": "Under the Dome",
  "type": "Scripted",
  "language": "English",
  "genres": [
    "Drama",
    "Science-Fiction",
    "Thriller"
  ],
  "status": "Ended",
  "runtime": 60,
  "averageRuntime": 60,
  "premiered": "2013-06-24",
  "ended": "2015-09-10",
  "officialSite": "http://www.cbs.com/shows/under-the-dome/",
  "scheduleTime": "22:00",
  "scheduleDays": [
    "Thursday"
  ],
  "ratingAverage": 6.6,
  "weight": 99,
  "networkName": "CBS",
  "networkCountry": "United States",
  "networkCode": "US",
  "networkTimezone": "America/New_York",
  "webChannelName": null,
  "imdbId": "tt1553656",
  "thetvdbId": 264492,
  "tvrageId": 25988,
  "imageMedium": "https://static.tvmaze.com/uploads/images/medium_portrait/610/1525272.jpg",
  "imageOriginal": "https://static.tvmaze.com/uploads/images/original_untouched/610/1525272.jpg",
  "summaryText": "Under the Dome is the story of a small town that is suddenly and inexplicably sealed off from the rest of the world by an enormous transparent dome. The town's inhabitants must deal with surviving the post-apocalyptic conditions while searching for answers about the dome, where it came from and if and when it will go away.",
  "summaryHtml": "<p><b>Under the Dome</b> is the story of a small town that is suddenly and inexplicably sealed off from the rest of the world by an enormous transparent dome. The town's inhabitants must deal with surviving the post-apocalyptic conditions while searching for answers about the dome, where it came from and if and when it will go away.</p>",
  "updatedAt": 1769177765,
  "url": "https://www.tvmaze.com/shows/1/under-the-dome"
}

⚠️ Run outcomes and error handling

This Actor reports what happened in the run's status message, and it always keeps whatever it collected. These are the outcomes you can get and what each one means.

Outcome	What it means
Success	Rows were returned and you were charged show-returned at $0.002 per row.
No matches	The source returned nothing for your filters. Nothing is charged. Widen the date window or drop a filter.

What is guaranteed either way

• Every row is pushed as it is built, not buffered to the end of the run. Anything that buffers output loses everything to a timeout, a block or a migration; this does not.
• A field absent from the source is absent from the row. Nothing is inferred, modelled or filled in to make a row look complete.