TV Shows Scraper: Episodes, Cast, Ratings & TV Schedules (TVmaze, Free)

No API key · Free TVmaze API · Episodes · Cast · Crew · Ratings · Schedules

A fast, no-key scraper for the free TVmaze API. Search a title, look a show up by IMDb or TheTVDB id, and export episodes with air dates and ratings, plus cast, crew, seasons, networks, and the daily TV schedule by country.

---

What you can do with it

Goal	How
Build episode guides	Pull a full season list with air dates, runtimes, and ratings
Show "what's on tonight"	Export the broadcast schedule for a country and date, web schedule optional
Track premieres for PR or ad sales	Collect premiere dates, network, and status without copying pages by hand
Resolve an IMDb or TheTVDB id	Send tt0903747 or tvdb:81189 and get the TVmaze show, cast, and ids
Build recommendation datasets	Page through the show index, or take shows updated in the last day, week, or month
Fill fan wikis	Grab alternate titles, seasons, and crew when you turn those options on

---

What it extracts

Show rows carry the TVmaze id and URL, the show name (showTitle, also stored as name and title), kind (showKind, also type), language, genres, status, runtimes, premiere and end dates, schedule time and days, rating, network or web channel, IMDb, TheTVDB, and TVRage ids, image URL, a plain-text summary, and optional akas, seasons, cast, crew, and episodes.

Episode and schedule rows carry the episode id and URL, the show id and title, season, number, episode name, episode kind, air date, air time, airstamp with its offset, runtime, rating, summary, image, network, web channel, and the schedule country when you requested one.

People rows carry the person id, name, birthday, death day, gender, country, image, and cast credits (show, character, self, voice). Update rows are a show id plus an ISO timestamp.

A miss or a hard failure becomes its own row: input, mode, error (NOT_FOUND, RATE_LIMITED, or HTTP_<code>), and statusCode. Duplicate ids in a run are dropped, and the run stops at maxItems.

---

Input

Parameter	Type	Default	Description
mode	string	search	Search, show details, episodes, people, schedule, updates, or the show index.
queries	array	breaking bad	Show titles or person names, one per line.
bestMatchOnly	boolean	false	One singlesearch hit per query. A miss becomes NOT_FOUND.
showIds	array	169	TVmaze id, show URL, IMDb id (tt0903747), or TheTVDB id (tvdb:81189).
includeEpisodes	boolean	true	Attach episodes in shows mode.
includeSpecials	boolean	false	Call the episodes endpoint with specials=1.
includeCast	boolean	true	Embed cast on the show request.
includeCrew	boolean	false	Extra request for crew.
includeSeasons	boolean	false	Extra request for seasons.
includeAkas	boolean	false	Extra request for alternate titles.
episodeRows	boolean	false	Write episodes as their own rows in shows mode.
countries	array	US	ISO-2 codes for the broadcast schedule.
dates	array	today (UTC)	YYYY-MM-DD. Empty means today.
includeWebSchedule	boolean	false	Also fetch the streaming/web schedule for each date.
updatedSince	string	day	day, week, or month for the updates feed.
fetchUpdatedShows	boolean	false	Load a full show row for each updated id.
indexStartPage	integer	0	First show-index page. The run stops on the first 404.
maxItems	integer	200	Row cap. Maximum 20,000.
callsPer10s	integer	18	Calls allowed in any 10-second window. Maximum 20.
timeoutSecs	integer	300	Stop the run after this many seconds.
requestTimeoutSecs	integer	30	Per-request timeout.
proxyConfiguration	object	no proxy	Optional. Apify Proxy stays off unless you turn it on.

How the lists map to each mode: search uses queries; schedule uses countries and dates; people search uses queries, then loads cast credits for each person; the index walks /shows?page= from indexStartPage until TVmaze returns 404.

Example input

{
    "mode": "shows",
    "showIds": ["169", "tt0903747", "tvdb:81189"],
    "includeEpisodes": true,
    "includeCast": true,
    "episodeRows": false,
    "maxItems": 200,
    "proxyConfiguration": { "useApifyProxy": false }
}

---

Output

{
    "tvmazeId": 169,
    "tvmazeUrl": "https://www.tvmaze.com/shows/169/breaking-bad",
    "showTitle": "Breaking Bad",
    "name": "Breaking Bad",
    "showKind": "Scripted",
    "status": "Ended",
    "premiered": "2008-01-20",
    "ended": "2019-10-11",
    "genres": ["Drama", "Crime", "Thriller"],
    "rating": 9.2,
    "network": {"name": "AMC", "country": "US", "timezone": "America/New_York"},
    "imdbId": "tt0903747",
    "thetvdbId": 81189,
    "episodesCount": 62,
    "cast": [{"personId": 14245, "name": "Bryan Cranston", "character": "Walter White"}],
    "source": "TVmaze (CC BY-SA)"
}

Field	Type	Description
showTitle	string	Show name. Also stored as title and name on show rows.
showKind	string	Scripted, Reality, and similar. Also stored as type on the show row.
episodeKind	string	regular, significant_special, and other TVmaze episode kinds. Also stored as type.
summary	string	HTML stripped to plain text.
network	object	name, country, timezone. Null on streaming-only shows.
webChannel	object	name and country when the show is on a web channel.
cast	array	Person, character, birthday, gender, country, self, voice.
crew	array	crewRole (also stored as type), person id, and name.
airstamp	string	ISO 8601 time with the original offset.
country	string	Country you requested for a schedule row.
error	string	NOT_FOUND, RATE_LIMITED, or HTTP_<code>.
source	string	TVmaze (CC BY-SA) on every row.

The dataset views are shows, episodes, schedule, and errors.

---

How it works

1. Reads mode and the lists for that mode.
2. Calls only public https://tvmaze.com routes: search, singlesearch, IMDb/TheTVDB lookup, show with episode and cast embeds, episodes, seasons, cast, crew, akas, country schedule, web schedule, people search, cast credits, the show index, and show updates.
3. Sends the User-Agent string TVmaze asks clients to send.
4. Keeps at most callsPer10s calls in any 10-second window (default 18, hard max 20) and at most 4 requests in flight. On HTTP 429 it waits 10 seconds plus a short jitter and retries up to 3 times.
5. Strips HTML from summaries, drops duplicate ids, and stops at maxItems or timeoutSecs. Nested episode arrays are capped at 500 per show so a daily news show does not land as one giant row. Turn on episodeRows for one row per episode, still under maxItems.

---

FAQ

Do I need a TVmaze API key? No. This actor uses the public API only. It does not call the premium or user API.

How many calls will it make? By default, 18 calls in each 10-second window, under TVmaze's 20 per 10 seconds per IP. Show details prefer embeds, so episodes and cast share one request. Crew, seasons, akas, and specials are separate requests and run only when you enable them.

What happens when a show or singlesearch query is missing? You get an error row with error set to NOT_FOUND. The show index treats 404 as the last page and stops, which is how TVmaze ends the index. An empty schedule is not an error.

Can it look up an IMDb id or a TheTVDB id? Yes. tt0903747, imdb:tt0903747, and tvdb:81189 resolve through the lookup endpoint and then load as a show. A TVmaze show URL works too.

Why is the nested episode list shorter than episodesCount? episodesCount is the full count. The nested episodes array stops at 500 (or at maxItems when that is lower) and sets episodesTruncated to true. Use episodes mode, or episodeRows, for one row per episode up to the run cap.

---

Trademark notice

TVmaze and related names, logos, and trademarks belong to their respective owners. Their use in this documentation is solely to identify the source of the data and does not imply affiliation, sponsorship, endorsement, or partnership.

Disclaimer

This actor is an independent tool and is not affiliated with, endorsed by, sponsored by, or otherwise officially associated with TVmaze.

Is web scraping legal?

Collecting information that is already public is generally legal. Scraping is not the same as hacking, and no single law bans it. The usual limits apply: do not break into accounts, do not take private or confidential data, and be careful with personal data and copyrighted works. A site's terms can also restrict how you access it. Facts such as a public name, price, or rating are not the same as republishing someone's article or photo.

This actor reads public pages and official public APIs. It does not log in and it does not bypass access controls.

This is not legal advice. For the longer explanation, see Apify's article Is web scraping legal?.