tvmaze.com APIwww.tvmaze.com ↗
Search TV shows, get full details, list all episodes, and look up by IMDb ID via the TVmaze database. Four endpoints, structured JSON responses.
curl -X GET 'https://api.parse.bot/scraper/f87c5156-8f01-4689-890e-d78df8810fe4/search_shows?query=breaking+bad' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed Python client. Install the CLI, sign in, then pull this API’s generated client:
pip install parse-sdk parse login parse add --marketplace tvmaze-com-api
parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TVmaze SDK — search shows, drill into details, list episodes."""
from parse_apis.TVmaze_API import TVmaze, ShowNotFound
client = TVmaze()
# Search for shows by name — limit caps total items fetched.
for result in client.shows.search(query="breaking bad", limit=5):
print(result.name, result.rating, result.genres)
# Drill into the first result's full details via the navigation op.
hit = client.shows.search(query="the office", limit=1).first()
if hit:
show = hit.details()
print(show.name, show.status, show.network.name, show.rating)
# List episodes for that show via sub-resource.
for ep in show.episodes.list(limit=3):
print(f" S{ep.season}E{ep.number}: {ep.name} (aired {ep.airdate}, rating {ep.rating})")
# Look up a show by IMDb ID directly.
show = client.shows.lookup_by_imdb(imdb_id="tt0944947")
print(show.name, show.genres, show.premiered)
# Typed error handling for a non-existent show.
try:
bad = client.shows.lookup_by_imdb(imdb_id="tt0000000")
except ShowNotFound as exc:
print(f"Not found: {exc}")
print("exercised: shows.search / details / episodes.list / lookup_by_imdb / ShowNotFound")
Full-text search over TV shows by name. Returns matching shows with relevance score, premiere date, genres, rating, and status. Results are ordered by relevance score descending. The API returns all matches in a single page (typically under 10 results).
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search query to match against show names. |
{
"type": "object",
"fields": {
"total": "integer count of results returned",
"results": "array of show search result objects with score, id, name, premiered, genres, rating, status, language, url"
},
"sample": {
"data": {
"total": 8,
"results": [
{
"id": 169,
"url": "https://www.tvmaze.com/shows/169/breaking-bad",
"name": "Breaking Bad",
"score": 1.1968992,
"genres": [
"Drama",
"Crime",
"Thriller"
],
"rating": 9.2,
"status": "Ended",
"language": "English",
"premiered": "2008-01-20"
}
]
},
"status": "success"
}
}About the tvmaze.com API
This API exposes 4 endpoints covering TVmaze's TV show database — from full-text show search to complete episode lists. The search_shows endpoint returns relevance-scored results with premiere date, genres, rating, and status. get_episodes delivers every episode across all seasons for a given show, including airdate, runtime, and per-episode rating. Lookups work by either TVmaze ID or IMDb ID.
Search and Discovery
The search_shows endpoint accepts a query string and returns an array of matching shows ordered by relevance score descending. Each result includes the TVmaze id, name, premiered date, genres, language, status, rating, and a direct url to the TVmaze page. Results are returned in a single page — typically under 10 entries — so there is no pagination to handle.
Show Details
Once you have a TVmaze numeric ID, get_show returns the full record for that show. Response fields include type (scripted, reality, etc.), network (with name and country), status, ended date (or null if ongoing), image URLs in both medium and original sizes, and a rating number. The lookup_show_by_imdb endpoint exposes the same field set but accepts an IMDb identifier in ttNNNNNNN format instead — useful when your source data uses IMDb IDs rather than TVmaze IDs.
Episode Data
The get_episodes endpoint takes a show_id and returns every episode ever recorded for that show. Each episode object contains season, number, name, type, airdate, airtime, runtime, rating, summary, and a url. The total field at the top level gives the count of episodes returned, which covers all seasons in a single response with no pagination.
The tvmaze.com API is a managed, monitored endpoint for www.tvmaze.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when www.tvmaze.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official www.tvmaze.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a TV show search feature using
search_showsresults filtered by genre or status - Populate a show detail page with network, schedule, and image data from
get_show - Cross-reference your IMDb-based watchlist with TVmaze records using
lookup_show_by_imdb - Generate episode guides with airdate and runtime data from
get_episodes - Track whether a series is ongoing or ended using the
statusandendedfields - Aggregate per-episode and per-show ratings to compare across a genre
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TVmaze have an official developer API?+
What does `get_episodes` return, and does it support filtering by season?+
season, number, airdate, runtime, rating, and summary, so you can filter the array by season number client-side after receiving the full list.Does `search_shows` support pagination or return more than the first page of results?+
Does the API return cast, crew, or character data for a show?+
What is the difference between `get_show` and `lookup_show_by_imdb` in terms of returned data?+
id, name, type, status, ended, genres, rating, network, image, and url. The only difference is the lookup key — get_show uses a TVmaze numeric show_id, while lookup_show_by_imdb accepts an IMDb identifier like tt0903747.