TVmaze

TVmaze is a community-driven TV show database that publishes a free RESTful API for TV show, episode, season, cast, crew, and broadcast/streaming schedule data. The public API is anonymous, CORS-enabled, and licensed under CC BY-SA 4.0. A paid Premium subscription unlocks a separate user-scoped API for managing follows, votes, marks, tags, and scrobbling.

2 APIs 10 Features

VideoTelevisionStreamingScheduleMetadataEntertainmentPublic APIs

APIs

TVmaze Public API

Anonymous, free REST API for shows, episodes, seasons, cast, crew, schedules, and incremental updates. Rate limit is at least 20 calls every 10 seconds per IP. Most endpoints ar...

TVmaze Premium User API

User-scoped REST API available only to Premium subscribers. Provides read-write access to a user's followed shows/people/networks/web-channels, marked episodes, voted shows and ...

Collections

TVmaze Premium User API

OPEN

TVmaze Public API

OPEN

Pricing Plans

Tvmaze Plans Pricing

5 plans

PLANS

Rate Limits

Tvmaze Rate Limits

0 limits

RATE LIMITS

FinOps

Tvmaze Finops

FINOPS

Features

Free Public API

No API key required for read access to shows, episodes, schedules, cast, crew, people.

Premium User API

HTTP-Basic authenticated user-scoped API for follows, marks, votes, tags, and scrobbling.

Device Auth Pairing

/v1/auth/start + /v1/auth/poll flow lets third-party apps obtain a user's API key without prompting for the password.

External ID Lookup

Resolve a show by TVRage, TheTVDB, or IMDb identifier.

Embedded Related Resources

Use ?embed= to fold cast, episodes, seasons, nextepisode, or previousepisode into a single show response.

Incremental Sync

/updates/shows and /updates/people return timestamp maps for efficient catch-up jobs.

Country-Aware Schedules

/schedule and /schedule/web accept an ISO country code and date to produce localized listings.

Full Future Schedule

/schedule/full returns every known future episode for bulk ingestion (cached 24h).

Bulk Scrobbling

Submit batches of viewing events through /v1/scrobble/episodes — available to free users too.

CC BY-SA Licensed Data

Data is freely usable with attribution to tvmaze.com.

Use Cases

TV Calendar Apps

Build a personal TV calendar driven by /schedule and Premium /v1/user/follows/shows.

Streaming Discovery

Power show search and recommendation flows with /search/shows and ?embed= calls.

Media Center Integrations

Sync show, episode, and image metadata into Plex, Kodi, Emby, Jellyfin, or Stremio plugins.

Trakt-Style Scrobblers

Use /v1/scrobble/episodes to record viewing history from media players.

AI Agents and Chatbots

Front the public API through MCP servers (e.g. mcp-tvmaze) to give LLM agents structured TV knowledge.

Data Science / Research

Bulk-ingest /shows, /people, and /schedule/full pages for analytics and ML training.

Integrations

Trakt.tv

Many Trakt-style workflows mirror TVmaze IDs and metadata.

Plex / Kodi / Emby

Media-center plugins read TVmaze metadata for show artwork, episode info, and airdates.

Stremio

Stremio addons (e.g. tvmaze-addon) surface TVmaze schedules in the catalog UI.

Sonarr / Radarr family

Several PVR ecosystems consume TVmaze as a fallback metadata provider.

Model Context Protocol (MCP)

Community MCP servers (mcp-tvmaze, tvmaze-mcp-server, 3cat-tvmaze-mcp) expose TVmaze as agent tools.

Apify TVmaze Scraper

Apify hosts a TVmaze scraper actor with its own OpenAPI definition.

Solutions

Free Personal Use

Anonymous public API for hobby projects, dashboards, and personal calendars.

Premium Bronze

Entry-tier subscription unlocking the user API and tracking features.

Premium Silver

Adds custom iCal and RSS calendar feeds.

Premium Gold

Tops the tier with influence over feature development.

Enterprise / Commercial

Custom commercial licensing for high-volume or redistributive use beyond CC BY-SA personal use.

Semantic Vocabularies

Tvmaze Context

44 classes · 13 properties

JSON-LD

API Governance Rules

TVmaze API Rules

14 rules · 4 errors 7 warnings 3 info

GitHubOrganization

GitHubOrganization

📦

Python TVmaze SDK (community, maintained by the TVmaze GitHub org)

Sources

opencollection: 1.0.0
info:
  name: TVmaze Public API
  version: '1.0'
items:
- info:
    name: Search
    type: folder
  items:
  - info:
      name: Search Shows
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/search/shows
      params:
      - name: q
        value: ''
        type: query
        description: Search query string.
    docs: Search for shows using a fuzzy text query.
  - info:
      name: Single Search Shows
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/singlesearch/shows
      params:
      - name: q
        value: ''
        type: query
      - name: embed
        value: ''
        type: query
    docs: Return the single best matching show for a query, optionally embedding related data.
  - info:
      name: Lookup Shows By External ID
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/lookup/shows
      params:
      - name: tvrage
        value: ''
        type: query
      - name: thetvdb
        value: ''
        type: query
      - name: imdb
        value: ''
        type: query
    docs: Look up a show using a TVRage, TheTVDB, or IMDb identifier.
  - info:
      name: Search People
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/search/people
      params:
      - name: q
        value: ''
        type: query
    docs: Search for people (actors, crew) using a fuzzy text query.
- info:
    name: Schedule
    type: folder
  items:
  - info:
      name: Get Schedule
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/schedule
      params:
      - name: country
        value: ''
        type: query
        description: ISO 3166-1 alpha-2 country code (default US).
      - name: date
        value: ''
        type: query
        description: ISO 8601 date (default today).
    docs: Return the TV schedule for a country on a given date.
  - info:
      name: Get Web Schedule
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/schedule/web
      params:
      - name: country
        value: ''
        type: query
      - name: date
        value: ''
        type: query
    docs: Return the web/streaming schedule for a country (or worldwide) on a given date.
  - info:
      name: Get Full Schedule
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/schedule/full
    docs: Return all future scheduled episodes (large response, cached 24h).
- info:
    name: Shows
    type: folder
  items:
  - info:
      name: List Shows
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows
      params:
      - name: page
        value: ''
        type: query
    docs: Paginated index of every show on TVmaze (250 per page).
  - info:
      name: Get Show
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
      - name: embed
        value: ''
        type: query
    docs: Return a single show, optionally embedding related resources.
  - info:
      name: Get Show Episodes
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/episodes
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
      - name: specials
        value: ''
        type: query
    docs: List every episode of a show, optionally including specials.
  - info:
      name: Get Show Episode By Number
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/episodebynumber
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
      - name: season
        value: ''
        type: query
      - name: number
        value: ''
        type: query
    docs: Return the specific episode for a show by season and episode number.
  - info:
      name: Get Show Episodes By Date
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/episodesbydate
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
      - name: date
        value: ''
        type: query
    docs: Return episodes that aired on a specific date for a show.
  - info:
      name: Get Show Seasons
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/seasons
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
    docs: Return the list of seasons for a show.
  - info:
      name: Get Show Cast
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/cast
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
    docs: Return the main cast of a show.
  - info:
      name: Get Show Crew
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/crew
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
    docs: Return the crew of a show.
  - info:
      name: Get Show Akas
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/akas
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
    docs: Return alternate titles (also-known-as) for a show.
  - info:
      name: Get Show Images
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/images
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
    docs: Return image assets associated with a show.
  - info:
      name: Get Show Alternate Lists
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/shows/:id/alternatelists
      params:
      - name: id
        value: ''
        type: path
        description: TVmaze show identifier.
    docs: Return alternate episode orderings for a show.
- info:
    name: Seasons
    type: folder
  items:
  - info:
      name: Get Season
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/seasons/:id
      params:
      - name: id
        value: ''
        type: path
    docs: Return a single season.
  - info:
      name: Get Season Episodes
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/seasons/:id/episodes
      params:
      - name: id
        value: ''
        type: path
    docs: Return the episodes of a season.
- info:
    name: Episodes
    type: folder
  items:
  - info:
      name: Get Episode
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/episodes/:id
      params:
      - name: id
        value: ''
        type: path
      - name: embed
        value: ''
        type: query
    docs: Return a single episode, optionally embedding related resources.
  - info:
      name: Get Episode Guest Cast
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/episodes/:id/guestcast
      params:
      - name: id
        value: ''
        type: path
    docs: Return the guest cast for an episode.
  - info:
      name: Get Episode Guest Crew
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/episodes/:id/guestcrew
      params:
      - name: id
        value: ''
        type: path
    docs: Return the guest crew for an episode.
- info:
    name: People
    type: folder
  items:
  - info:
      name: List People
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/people
      params:
      - name: page
        value: ''
        type: query
    docs: Paginated index of every person on TVmaze (1000 per page).
  - info:
      name: Get Person
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/people/:id
      params:
      - name: id
        value: ''
        type: path
    docs: Return a single person.
  - info:
      name: Get Person Cast Credits
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/people/:id/castcredits
      params:
      - name: id
        value: ''
        type: path
    docs: Return show-level cast credits for a person.
  - info:
      name: Get Person Crew Credits
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/people/:id/crewcredits
      params:
      - name: id
        value: ''
        type: path
    docs: Return show-level crew credits for a person.
  - info:
      name: Get Person Guest Cast Credits
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/people/:id/guestcastcredits
      params:
      - name: id
        value: ''
        type: path
    docs: Return episode-level guest cast credits for a person.
- info:
    name: Updates
    type: folder
  items:
  - info:
      name: Get Show Updates
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/updates/shows
      params:
      - name: since
        value: ''
        type: query
    docs: Return a map of show IDs to last-updated timestamps for incremental sync.
  - info:
      name: Get Person Updates
      type: http
    http:
      method: GET
      url: https://api.tvmaze.com/updates/people
      params:
      - name: since
        value: ''
        type: query
    docs: Return a map of person IDs to last-updated timestamps for incremental sync.
bundled: true