TVmaze

Implementation notes

When to use TVmaze

TVmaze is the best no-key option for television metadata: episode lists with real air dates and season/episode numbering, cast with character mappings, network and country data, and daily and weekly broadcast schedules. No signup, no key, no quota dashboard, and a REST shape that has stayed stable for years. It is the right pick for episode trackers, calendar and reminder apps, and anything that has to answer what aired last night or when the next episode drops. The dataset is community-curated but well-policed — air dates are accurate for mainstream shows and updated ahead of broadcast rather than after it. Where it loses to TMDB is imagery and non-English metadata, and it does not cover films at all. Where it wins is that the episode is a first-class entity rather than a sub-resource, and you can pull a show with its entire episode list and cast in a single request.

Common pitfalls

• No key means the rate limit is per IP, at roughly 20 calls per 10 seconds. On shared CI runners, serverless platforms, or anything behind corporate NAT you are sharing that budget with strangers, so 429s show up in test suites that pass fine on a laptop. Respect Retry-After, and record fixtures for CI instead of hitting the live API in every test.
• Fetching a show and then looping over its episodes is the default mistake. Embedding avoids it: /shows/82?embed[]=episodes&embed[]=cast returns the show, every episode, and the full cast in one response. The bracket syntax matters — a single ?embed=episodes works, but ?embed=episodes&embed=cast silently keeps only the last one and you quietly lose the other resource.
• TVmaze IDs are TVmaze IDs. They have no relationship to IMDb, TheTVDB, or TMDB IDs. Cross-reference through /lookup/shows?imdb=tt0944947 or ?thetvdb=121361, which returns the show object directly rather than a results array — a different response shape from /search/shows, so shared parsing code will break on one of them.
• Schedule endpoints are country-scoped and default to the US. /schedule with no parameters returns today's US broadcast schedule in US Eastern time, and /schedule/web returns streaming releases which follow completely different timing rules. For a global audience use /schedule/full or an explicit country code, and treat every airstamp as UTC and format it locally.

Quick start (bash)

# show + every episode + full cast in one request instead of N+1
curl -s 'https://api.tvmaze.com/shows/82?embed[]=episodes&embed[]=cast' | jq '.name, (._embedded.episodes | length)'
# cross-reference from an IMDb ID (returns the show object, not an array)
curl -s 'https://api.tvmaze.com/lookup/shows?imdb=tt0944947' | jq '.id, .name'

Embed this badge

Add a live status badge to your README, docs, or website.

Markdown

[![TVmaze Status](https://api.freeapi.watch/badge/tvmaze.svg)](https://freeapi.watch/tvmaze)

HTML

<a href="https://freeapi.watch/tvmaze"><img src="https://api.freeapi.watch/badge/tvmaze.svg" alt="TVmaze Status"/></a>