TVmaze

Look up TV shows, episodes, seasons, cast, crew, and air schedules on TVmaze, and, with a TVmaze account, follow shows, tag them, vote, and track what you have watched. The whole catalogue is free and needs no API key; add your username and key only for the account actions.

Actions

Action	What it does
Check if an episode is marked	Check whether one episode is marked on your TVmaze account, and how.
Check if you follow something	Check whether your TVmaze account follows one show, person, network or streaming service.
Check TVmaze credentials	Check that this connection's TVmaze username and API key work, and report whether the account has Premium.
Check your vote	Check whether your TVmaze account has voted for one show or episode, and with what.
Create a tag	Create a new tag on your TVmaze account.
Delete a tag	Delete one of your TVmaze tags.
Find one show	Find the single show TVmaze thinks a name means, without picking from a list.
Follow something	Follow a show, person, network or streaming service on your TVmaze account.
Get a person	Get one person's details by their TVmaze id: name, country, birthday, and headshot.
Get a person's acting credits	List the shows a person has been cast in, each with the character they played.
Get a person's crew credits	List the shows a person has crewed on, each with the job they did.
Get a person's guest appearances	List the individual episodes a person guest-starred in, each with the episode and the character.
Get a season's episodes	List the episodes in one season, specials included.
Get a show	Get one TV show's full details by its TVmaze id, including network, genres, air schedule, rating, summary, its IMDb id, and which episode aired last and which airs next.
Get a show's alternate episode orders	List the alternate episode orderings a show has: DVD order, a broadcaster's own numbering, a streaming re-cut.
Get a show's cast	List a show's main cast, each performer with the character they play, ordered by how much the character appears.
Get a show's crew	List a show's main crew, each with the job they did: creator, executive producer, composer and so on.
Get a show's episodes	List every episode of a show in airing order, with season and episode numbers, air dates, ratings, and synopses.
Get a show's episodes by date	List the episodes of one show that aired on a given date.
Get a show's images	List every image TVmaze holds for a show (posters, banners, backgrounds and typography) at full size, and at medium size where one exists.
Get a show's other titles	List the other names a show goes by.
Get a show's seasons	List a show's seasons in order, each with its episode count, premiere and end dates, and the network that carried it.
Get an alternate episode order	List the episodes in one alternate ordering, each mapped back to the episode TVmaze numbers normally, which is what lets a DVD episode number be turned into the broadcast one.
Get an episode	Get one episode by its TVmaze id, together with the show it belongs to.
Get an episode by number	Get one episode of a show by its season and episode number, without pulling the whole episode list.
Get an episode's guest cast	List the guest cast of one episode: the performers who appear in it but are not part of the show's main cast.
Get an episode's guest crew	List the guest crew of one episode, most often the director and writers credited on that episode alone.
Get recently changed people	List the people TVmaze changed recently, most recent first.
Get recently changed shows	List the shows TVmaze changed recently, most recent first, so a local copy can be refreshed without re-reading the catalogue.
Get the full future schedule	List every future episode TVmaze knows about, anywhere in the world, filtered to the country and dates you want.
Get the streaming schedule	List the episodes released on streaming services on a given day.
Get the TV schedule	List the TV episodes airing in a country on a given day, each with the show it belongs to.
List all people	Read one page of every person in the TVmaze database, 1000 to a page.
List all shows	Read one page of the whole TVmaze catalogue, 250 shows to a page, for building or refreshing a local copy.
List marked episodes	List the episodes marked on your TVmaze account.
List marked episodes for a show	List what you have marked for one show: watched, acquired, skipped, or all three.
List shows under a tag	List the shows filed under one of your TVmaze tags, each in full rather than as a bare id.
List tags	List the tags on your TVmaze account.
List what you follow	List the shows, people, networks or streaming services your TVmaze account follows.
List your votes	List the votes your TVmaze account has cast, on shows or on episodes.
Look up a show by IMDb or TheTVDB id	Find a TVmaze show from its id on another service: IMDb, TheTVDB or TVRage.
Mark an episode	Mark an episode as watched, acquired or skipped on your TVmaze account.
Mark episodes of a show by number	Mark episodes of one show using season and episode numbers, or air dates, instead of TVmaze episode ids, and name the show by its TVmaze, TheTVDB or IMDb id.
Mark many episodes	Mark a batch of episodes by their TVmaze episode ids in one request.
Poll a TVmaze authentication request	Check whether a user has confirmed an authentication request, and collect their API key once they have.
Remove your vote	Remove your TVmaze vote from a show or an episode.
Rename a tag	Rename one of your TVmaze tags.
Search people	Search TVmaze for actors and crew by name and get back each match with their id, country, birthday, and headshot.
Search shows	Search TVmaze for TV shows by name and get back each match with its id, network, genres, status, rating, and summary.
Start a TVmaze authentication request	Ask TVmaze to start authenticating a user by email, so you can get their API key without ever handling their password.
Tag a show	File a show under one of your TVmaze tags.
Unfollow something	Stop following a show, person, network or streaming service.
Unmark an episode	Remove an episode's mark from your TVmaze account.
Untag a show	Take a show out of one of your TVmaze tags.
Vote for a show or episode	Cast a vote from 1 to 10 for a show or an episode on your TVmaze account.

Check if an episode is marked

Check whether one episode is marked on your TVmaze account, and how. Not marked comes back as marked false, not as a failure. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Episode IDepisode_idnumberRequired: The TVmaze id of the episode to check.

Outputs

episodeobject: The mark, or null if there is none.
markedtrue/false: Whether the episode is marked at all.

Example output

{
  "episode": {
    "episode": {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    },
    "episode_id": 4952,
    "marked_at": "2024-03-02T20:14:00+00:00",
    "marked_timestamp": 1709410440,
    "type": 0,
    "type_label": "watched"
  },
  "marked": true
}

Check if you follow something

Check whether your TVmaze account follows one show, person, network or streaming service. Not followed comes back as followed false, not as a failure. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingfollow_typetext: What is being followed. TVmaze keeps a separate list for each kind, so this decides which list is read or written.One of: show, person, network, webchannel (Streaming service). Default: show.
TVmaze IDitem_idnumberRequired: The TVmaze id of the show, person, network or streaming service to check.

Outputs

followobject: The follow record, or null if not followed.
followedtrue/false: Whether this account follows it.
idnumber: The id that was checked.
typetext: The kind that was checked.

Example output

{
  "follow": {
    "details": {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    },
    "id": 82,
    "name": "Game of Thrones",
    "type": "show",
    "url": "https://www.tvmaze.com/shows/82/game-of-thrones"
  },
  "followed": true,
  "id": 82,
  "type": "show"
}

Check TVmaze credentials

Check that this connection's TVmaze username and API key work, and report whether the account has Premium. Worth running first in any workflow that uses the account actions: a wrong key and a lapsed subscription otherwise both surface as a failure on whichever action happens to run first.

Inputs

None.

Outputs

is_premiumtrue/false: Whether the premium-only actions will work.
premiumnumber: The account's premium level. 0 means none.
validtrue/false: Whether TVmaze accepted the username and key.

Example output

{
  "is_premium": true,
  "premium": 1,
  "valid": true
}

Check your vote

Check whether your TVmaze account has voted for one show or episode, and with what. Never voted comes back as voted false. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingvote_typetext: Whether the vote is on a show or on a single episode.One of: show, episode. Default: show.
TVmaze IDitem_idnumberRequired: The TVmaze id of the show or episode to check.

Outputs

idnumber: The id that was checked.
typetext: The kind that was checked.
voteobject: The vote, or null if there is none.
votedtrue/false: Whether a vote exists.

Example output

{
  "id": 82,
  "type": "show",
  "vote": {
    "details": {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    },
    "id": 82,
    "type": "show",
    "vote": 9,
    "voted_at": "2024-03-02T20:15:11+00:00",
    "voted_timestamp": 1709410511
  },
  "voted": true
}

Create a tag

Create a new tag on your TVmaze account. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Tag namenametextRequired: What to call it, for example "Watching with the kids".

Outputs

tagobject: The tag that was created.

Example output

{
  "tag": {
    "id": 417,
    "name": "Watching with the kids"
  }
}

Delete a tag

Delete one of your TVmaze tags. This removes the tag itself; the shows that carried it are not otherwise affected. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Tag IDtag_idnumberRequired: The TVmaze id of the tag, from List tags.

Outputs

deletedtrue/false: True if a tag was deleted, false if there was no such tag.
tag_idnumber: The tag acted on.

Example output

{
  "deleted": true,
  "tag_id": 417
}

Find one show

Find the single show TVmaze thinks a name means, without picking from a list. Returns one show or none; check 'found' before using it. Two shows with the same name (Top Gear) make which one comes back undefined, so use Search shows when that matters. No API key required.

Inputs

Show namequerytextRequired: The show name, for example "game of thrones". Small typos are tolerated, though less than in Search shows.

Outputs

foundtrue/false: Whether TVmaze matched the name to a show.
showobject: The show, or null if nothing matched.

Example output

{
  "found": true,
  "show": {
    "average_runtime": 61,
    "ended": "2019-05-19",
    "genres": [
      "Drama",
      "Adventure",
      "Fantasy"
    ],
    "id": 82,
    "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
    "imdb_id": "tt0944947",
    "language": "English",
    "name": "Game of Thrones",
    "network": {
      "country": {
        "code": "US",
        "name": "United States",
        "timezone": "America/New_York"
      },
      "id": 8,
      "name": "HBO"
    },
    "next_episode": null,
    "official_site": "http://www.hbo.com/game-of-thrones",
    "premiered": "2011-04-17",
    "previous_episode": {
      "id": 1623968,
      "name": "The Iron Throne",
      "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
    },
    "rating": 8.9,
    "runtime": 60,
    "schedule_days": [
      "Sunday"
    ],
    "schedule_time": "21:00",
    "status": "Ended",
    "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
    "thetvdb_id": 121361,
    "tvrage_id": 24493,
    "type": "Scripted",
    "updated_at": "2024-11-15T09:12:41+00:00",
    "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
    "web_channel": null,
    "weight": 99
  }
}

Follow something

Follow a show, person, network or streaming service on your TVmaze account. Following something already followed is not an error, so a sync workflow need not check first. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingfollow_typetext: What is being followed. TVmaze keeps a separate list for each kind, so this decides which list is read or written.One of: show, person, network, webchannel (Streaming service). Default: show.
TVmaze IDitem_idnumberRequired: The TVmaze id of the show, person, network or streaming service to follow.

Outputs

followobject: What is now followed.
typetext: The kind that was followed.

Example output

{
  "follow": {
    "details": {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    },
    "id": 82,
    "name": "Game of Thrones",
    "type": "show",
    "url": "https://www.tvmaze.com/shows/82/game-of-thrones"
  },
  "type": "show"
}

Get a person

Get one person's details by their TVmaze id: name, country, birthday, and headshot. No API key required.

Inputs

Person IDperson_idnumberRequired: The TVmaze id of the person, for example 29. Search people first if you only have the name.

Outputs

personobject: The person's details.

Example output

{
  "person": {
    "birthday": "1969-06-11",
    "country": {
      "code": "US",
      "name": "United States",
      "timezone": "America/New_York"
    },
    "deathday": null,
    "gender": "Male",
    "id": 29,
    "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/863.jpg",
    "name": "Peter Dinklage",
    "url": "https://www.tvmaze.com/people/29/peter-dinklage"
  }
}

Get a person's acting credits

List the shows a person has been cast in, each with the character they played. Both the show and the character come back in full, so no follow-up lookups are needed. No API key required.

Inputs

Person IDperson_idnumberRequired: The TVmaze id of the person, for example 29. Search people first if you only have the name.

Outputs

countnumber: How many credits were returned.
creditslist: Shows they were cast in.

Example output

{
  "count": 1,
  "credits": [
    {
      "character": {
        "id": 10,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/1360.jpg",
        "name": "Tyrion Lannister",
        "url": "https://www.tvmaze.com/characters/10/game-of-thrones-tyrion-lannister"
      },
      "self": false,
      "show": {
        "average_runtime": 61,
        "ended": "2019-05-19",
        "genres": [
          "Drama",
          "Adventure",
          "Fantasy"
        ],
        "id": 82,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
        "imdb_id": "tt0944947",
        "language": "English",
        "name": "Game of Thrones",
        "network": {
          "country": {
            "code": "US",
            "name": "United States",
            "timezone": "America/New_York"
          },
          "id": 8,
          "name": "HBO"
        },
        "next_episode": null,
        "official_site": "http://www.hbo.com/game-of-thrones",
        "premiered": "2011-04-17",
        "previous_episode": {
          "id": 1623968,
          "name": "The Iron Throne",
          "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
        },
        "rating": 8.9,
        "runtime": 60,
        "schedule_days": [
          "Sunday"
        ],
        "schedule_time": "21:00",
        "status": "Ended",
        "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
        "thetvdb_id": 121361,
        "tvrage_id": 24493,
        "type": "Scripted",
        "updated_at": "2024-11-15T09:12:41+00:00",
        "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
        "web_channel": null,
        "weight": 99
      },
      "voice": false
    }
  ]
}

Get a person's crew credits

List the shows a person has crewed on, each with the job they did. The show comes back in full. No API key required.

Inputs

Person IDperson_idnumberRequired: The TVmaze id of the person, for example 29. Search people first if you only have the name.

Outputs

countnumber: How many credits were returned.
creditslist: Shows they crewed on.

Example output

{
  "count": 1,
  "credits": [
    {
      "show": {
        "average_runtime": 61,
        "ended": "2019-05-19",
        "genres": [
          "Drama",
          "Adventure",
          "Fantasy"
        ],
        "id": 82,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
        "imdb_id": "tt0944947",
        "language": "English",
        "name": "Game of Thrones",
        "network": {
          "country": {
            "code": "US",
            "name": "United States",
            "timezone": "America/New_York"
          },
          "id": 8,
          "name": "HBO"
        },
        "next_episode": null,
        "official_site": "http://www.hbo.com/game-of-thrones",
        "premiered": "2011-04-17",
        "previous_episode": {
          "id": 1623968,
          "name": "The Iron Throne",
          "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
        },
        "rating": 8.9,
        "runtime": 60,
        "schedule_days": [
          "Sunday"
        ],
        "schedule_time": "21:00",
        "status": "Ended",
        "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
        "thetvdb_id": 121361,
        "tvrage_id": 24493,
        "type": "Scripted",
        "updated_at": "2024-11-15T09:12:41+00:00",
        "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
        "web_channel": null,
        "weight": 99
      },
      "type": "Executive Producer"
    }
  ]
}

Get a person's guest appearances

List the individual episodes a person guest-starred in, each with the episode and the character. This is per episode, where Get a person's acting credits is per show. No API key required.

Inputs

Person IDperson_idnumberRequired: The TVmaze id of the person, for example 29. Search people first if you only have the name.

Outputs

countnumber: How many credits were returned.
creditslist: Episodes they guested in.

Example output

{
  "count": 1,
  "credits": [
    {
      "character": {
        "id": 10,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/1360.jpg",
        "name": "Tyrion Lannister",
        "url": "https://www.tvmaze.com/characters/10/game-of-thrones-tyrion-lannister"
      },
      "episode": {
        "airdate": "2011-04-17",
        "airstamp": "2011-04-18T01:00:00+00:00",
        "airtime": "21:00",
        "id": 4952,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
        "name": "Winter is Coming",
        "number": 1,
        "rating": 8.4,
        "runtime": 60,
        "season": 1,
        "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
        "type": "regular",
        "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
      },
      "self": false,
      "voice": false
    }
  ]
}

Get a season's episodes

List the episodes in one season, specials included. Can also bring back each episode's guest cast in the same request, which is far cheaper than asking per episode. Takes a season id, not a show id; get one from Get a show's seasons. No API key required.

Inputs

Season IDseason_idnumberRequired: The TVmaze id of the season, for example 249. Get one from Get a show's seasons.
Include guest castinclude_guest_casttrue/false: Add each episode's guest cast to the result. One extra request in total rather than one per episode.Default: false.

Outputs

countnumber: How many episodes were returned.
episodeslist: The season's episodes, in airing order.

Example output

{
  "count": 1,
  "episodes": [
    {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "guest_cast": [],
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    }
  ]
}

Get a show

Get one TV show's full details by its TVmaze id, including network, genres, air schedule, rating, summary, its IMDb id, and which episode aired last and which airs next. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.

Outputs

showobject: The show's details.

Example output

{
  "show": {
    "average_runtime": 61,
    "ended": "2019-05-19",
    "genres": [
      "Drama",
      "Adventure",
      "Fantasy"
    ],
    "id": 82,
    "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
    "imdb_id": "tt0944947",
    "language": "English",
    "name": "Game of Thrones",
    "network": {
      "country": {
        "code": "US",
        "name": "United States",
        "timezone": "America/New_York"
      },
      "id": 8,
      "name": "HBO"
    },
    "next_episode": null,
    "official_site": "http://www.hbo.com/game-of-thrones",
    "premiered": "2011-04-17",
    "previous_episode": {
      "id": 1623968,
      "name": "The Iron Throne",
      "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
    },
    "rating": 8.9,
    "runtime": 60,
    "schedule_days": [
      "Sunday"
    ],
    "schedule_time": "21:00",
    "status": "Ended",
    "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
    "thetvdb_id": 121361,
    "tvrage_id": 24493,
    "type": "Scripted",
    "updated_at": "2024-11-15T09:12:41+00:00",
    "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
    "web_channel": null,
    "weight": 99
  }
}

Get a show's alternate episode orders

List the alternate episode orderings a show has: DVD order, a broadcaster's own numbering, a streaming re-cut. Use a list's id with Get an alternate episode order. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.

Outputs

alternate_listslist: The show's alternate orderings.
countnumber: How many lists were returned.

Example output

{
  "alternate_lists": [
    {
      "country": {
        "code": "US",
        "name": "United States",
        "timezone": "America/New_York"
      },
      "dvd": true,
      "id": 1,
      "language": "English",
      "memo": "DVD ordering",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "url": "https://www.tvmaze.com/alternatelists/1/dvd-ordering",
      "verbatim": false,
      "web_channel": null
    }
  ],
  "count": 1
}

Get a show's cast

List a show's main cast, each performer with the character they play, ordered by how much the character appears. Marks roles played as themselves and voice-only roles. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.

Outputs

castlist: Cast members, most prominent first.
countnumber: How many cast members were returned.

Example output

{
  "cast": [
    {
      "character": {
        "id": 10,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/1360.jpg",
        "name": "Tyrion Lannister",
        "url": "https://www.tvmaze.com/characters/10/game-of-thrones-tyrion-lannister"
      },
      "person": {
        "birthday": "1969-06-11",
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "deathday": null,
        "gender": "Male",
        "id": 29,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/863.jpg",
        "name": "Peter Dinklage",
        "url": "https://www.tvmaze.com/people/29/peter-dinklage"
      },
      "self": false,
      "voice": false
    }
  ],
  "count": 1
}

Get a show's crew

List a show's main crew, each with the job they did: creator, executive producer, composer and so on. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.

Outputs

countnumber: How many crew members were returned.
crewlist: Crew members.

Example output

{
  "count": 1,
  "crew": [
    {
      "person": {
        "birthday": "1970-09-25",
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "deathday": null,
        "gender": "Male",
        "id": 25100,
        "image_url": null,
        "name": "David Benioff",
        "url": "https://www.tvmaze.com/people/25100/david-benioff"
      },
      "type": "Executive Producer"
    }
  ]
}

Get a show's episodes

List every episode of a show in airing order, with season and episode numbers, air dates, ratings, and synopses. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.
Include specialsinclude_specialstrue/false: Include specials in the list. Off by default, which is what keeps season and episode numbering contiguous.Default: false.

Outputs

countnumber: How many episodes were returned.
episodeslist: The show's episodes, in airing order.

Example output

{
  "count": 1,
  "episodes": [
    {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    }
  ]
}

Get a show's episodes by date

List the episodes of one show that aired on a given date. Built for daily shows (talk shows, soaps, news) where nobody refers to an episode by season and number. A day with nothing on it comes back empty rather than failing. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.
DatedatedateRequired: The air date to look for, as YYYY-MM-DD.

Outputs

countnumber: How many episodes were returned.
episodeslist: Episodes that aired on that date. Empty if none did.

Example output

{
  "count": 1,
  "episodes": [
    {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    }
  ]
}

Get a show's images

List every image TVmaze holds for a show (posters, banners, backgrounds and typography) at full size, and at medium size where one exists. The image marked 'main' is the show's primary one of that kind. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.
Image typeimage_typetext: Keep only images of one kind.One of: all (All types), poster, banner, background, typography. Default: all.

Outputs

countnumber: How many images were returned.
imageslist: The show's images.

Example output

{
  "count": 1,
  "images": [
    {
      "id": 476117,
      "main": true,
      "medium_url": "https://static.tvmaze.com/uploads/images/medium_portrait/190/476117.jpg",
      "original_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "type": "poster"
    }
  ]
}

Get a show's other titles

List the other names a show goes by. An entry with no country is an alternative title at home; one with a country is what the show is called there. Useful for matching titles from a foreign catalogue. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.

Outputs

akaslist: Alternative titles.
countnumber: How many titles were returned.

Example output

{
  "akas": [
    {
      "country": {
        "code": "FR",
        "name": "France",
        "timezone": "Europe/Paris"
      },
      "name": "Le Tr\u00f4ne de fer"
    }
  ],
  "count": 1
}

Get a show's seasons

List a show's seasons in order, each with its episode count, premiere and end dates, and the network that carried it. Use a season's id with Get a season's episodes. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.

Outputs

countnumber: How many seasons were returned.
seasonslist: The show's seasons, in order.

Example output

{
  "count": 1,
  "seasons": [
    {
      "end_date": "2011-06-19",
      "episode_order": 10,
      "id": 249,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/224/562044.jpg",
      "name": "",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "number": 1,
      "premiere_date": "2011-04-17",
      "summary": null,
      "url": "https://www.tvmaze.com/seasons/249/game-of-thrones-season-1",
      "web_channel": null
    }
  ]
}

Get an alternate episode order

List the episodes in one alternate ordering, each mapped back to the episode TVmaze numbers normally, which is what lets a DVD episode number be turned into the broadcast one. No API key required.

Inputs

Alternate list IDalternate_list_idnumberRequired: The id of the alternate list, from Get a show's alternate episode orders.

Outputs

alternate_episodeslist: Episodes in this ordering, each with the canonical episode.
countnumber: How many episodes were returned.

Example output

{
  "alternate_episodes": [
    {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "episode": {
        "airdate": "2011-04-17",
        "airstamp": "2011-04-18T01:00:00+00:00",
        "airtime": "21:00",
        "id": 4952,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
        "name": "Winter is Coming",
        "number": 1,
        "rating": 8.4,
        "runtime": 60,
        "season": 1,
        "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
        "type": "regular",
        "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
      },
      "id": 37,
      "name": "Winter is Coming",
      "number": 1,
      "runtime": 60,
      "season": 1,
      "url": "https://www.tvmaze.com/alternateepisodes/37"
    }
  ],
  "count": 1
}

Get an episode

Get one episode by its TVmaze id, together with the show it belongs to. Use it to turn an episode id from the schedule, or from a marked-episode list, back into something with a title and a show attached. No API key required.

Inputs

Episode IDepisode_idnumberRequired: The TVmaze id of the episode, for example 4952. Episode ids come from the schedule, a show's episode list, or Get an episode by number.

Outputs

episodeobject: The episode, with its show.

Example output

{
  "episode": {
    "airdate": "2011-04-17",
    "airstamp": "2011-04-18T01:00:00+00:00",
    "airtime": "21:00",
    "id": 4952,
    "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
    "name": "Winter is Coming",
    "number": 1,
    "rating": 8.4,
    "runtime": 60,
    "season": 1,
    "show": {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    },
    "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
    "type": "regular",
    "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
  }
}

Get an episode by number

Get one episode of a show by its season and episode number, without pulling the whole episode list. Returns nothing if that episode does not exist; check 'found', which is how you tell whether next week's episode has been listed yet. No API key required.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82. Search shows first if you only have the name.
Season numberseasonnumberRequired: The season number, for example 1.
Episode numbernumbernumberRequired: The episode number within that season, for example 1.

Outputs

episodeobject: The episode, or null if there is no such episode.
foundtrue/false: Whether that season and episode number exists.

Example output

{
  "episode": {
    "airdate": "2011-04-17",
    "airstamp": "2011-04-18T01:00:00+00:00",
    "airtime": "21:00",
    "id": 4952,
    "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
    "name": "Winter is Coming",
    "number": 1,
    "rating": 8.4,
    "runtime": 60,
    "season": 1,
    "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
    "type": "regular",
    "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
  },
  "found": true
}

Get an episode's guest cast

List the guest cast of one episode: the performers who appear in it but are not part of the show's main cast. No API key required.

Inputs

Episode IDepisode_idnumberRequired: The TVmaze id of the episode, for example 4952. Episode ids come from the schedule, a show's episode list, or Get an episode by number.

Outputs

countnumber: How many guest cast members were returned.
guest_castlist: Guest cast for this episode.

Example output

{
  "count": 1,
  "guest_cast": [
    {
      "character": {
        "id": 10,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/1360.jpg",
        "name": "Tyrion Lannister",
        "url": "https://www.tvmaze.com/characters/10/game-of-thrones-tyrion-lannister"
      },
      "person": {
        "birthday": "1969-06-11",
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "deathday": null,
        "gender": "Male",
        "id": 29,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/863.jpg",
        "name": "Peter Dinklage",
        "url": "https://www.tvmaze.com/people/29/peter-dinklage"
      },
      "self": false,
      "voice": false
    }
  ]
}

Get an episode's guest crew

List the guest crew of one episode, most often the director and writers credited on that episode alone. No API key required.

Inputs

Episode IDepisode_idnumberRequired: The TVmaze id of the episode, for example 4952. Episode ids come from the schedule, a show's episode list, or Get an episode by number.

Outputs

countnumber: How many guest crew members were returned.
guest_crewlist: Guest crew for this episode.

Example output

{
  "count": 1,
  "guest_crew": [
    {
      "person": {
        "birthday": "1970-09-25",
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "deathday": null,
        "gender": "Male",
        "id": 25100,
        "image_url": null,
        "name": "David Benioff",
        "url": "https://www.tvmaze.com/people/25100/david-benioff"
      },
      "type": "Executive Producer"
    }
  ]
}

Get recently changed people

List the people TVmaze changed recently, most recent first. A person counts as changed when their own details change and also when a credit involving them is added or removed. No API key required.

Inputs

Changed withinsincetext: How far back to look. Everything is the whole database, which is tens of thousands of rows; use it for a first sync only.One of: day (Last 24 hours), week (Last week), month (Last month), all (Everything). Default: day.
Limitlimitnumber: The most people to return, most recently changed first.From 1 to 1000. Default: 100.

Outputs

countnumber: How many people were returned.
sincetext: The window that was asked for.
total_availablenumber: How many people changed in that window. Larger than count means the limit trimmed the result.
updateslist: Changed people, most recent first.

Example output

{
  "count": 1,
  "since": "day",
  "total_available": 5103,
  "updates": [
    {
      "id": 29,
      "updated_at": "2024-11-15T09:12:41+00:00",
      "updated_timestamp": 1731661961
    }
  ]
}

Get recently changed shows

List the shows TVmaze changed recently, most recent first, so a local copy can be refreshed without re-reading the catalogue. A show counts as changed when anything under it changes, an episode or an image included. No API key required.

Inputs

Changed withinsincetext: How far back to look. Everything is the whole database, which is tens of thousands of rows; use it for a first sync only.One of: day (Last 24 hours), week (Last week), month (Last month), all (Everything). Default: day.
Limitlimitnumber: The most shows to return, most recently changed first.From 1 to 1000. Default: 100.

Outputs

countnumber: How many shows were returned.
sincetext: The window that was asked for.
total_availablenumber: How many shows changed in that window. Larger than count means the limit trimmed the result.
updateslist: Changed shows, most recent first.

Example output

{
  "count": 1,
  "since": "day",
  "total_available": 1842,
  "updates": [
    {
      "id": 82,
      "updated_at": "2024-11-15T09:12:41+00:00",
      "updated_timestamp": 1731661961
    }
  ]
}

Get the full future schedule

List every future episode TVmaze knows about, anywhere in the world, filtered to the country and dates you want. This is a large, slow response that TVmaze caches for 24 hours; use Get the TV schedule for a single day. Reports how many episodes matched before the limit was applied. No API key required.

Inputs

Country codecountrytext: Keep only episodes airing in this country, for example GB. Leave empty for every country.
From datedate_fromdate: Keep only episodes airing on or after this date.
To datedate_todate: Keep only episodes airing on or before this date.
Limitlimitnumber: The most episodes to return, soonest first.From 1 to 1000. Default: 100.

Outputs

countnumber: How many episodes were returned.
episodeslist: Matching episodes, soonest first, up to the limit.
matchednumber: How many episodes matched the filters. Larger than count means the limit trimmed the result.
total_availablenumber: How many future episodes TVmaze holds in total.

Example output

{
  "count": 1,
  "episodes": [
    {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "show": {
        "average_runtime": 61,
        "ended": "2019-05-19",
        "genres": [
          "Drama",
          "Adventure",
          "Fantasy"
        ],
        "id": 82,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
        "imdb_id": "tt0944947",
        "language": "English",
        "name": "Game of Thrones",
        "network": {
          "country": {
            "code": "US",
            "name": "United States",
            "timezone": "America/New_York"
          },
          "id": 8,
          "name": "HBO"
        },
        "next_episode": null,
        "official_site": "http://www.hbo.com/game-of-thrones",
        "premiered": "2011-04-17",
        "previous_episode": {
          "id": 1623968,
          "name": "The Iron Throne",
          "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
        },
        "rating": 8.9,
        "runtime": 60,
        "schedule_days": [
          "Sunday"
        ],
        "schedule_time": "21:00",
        "status": "Ended",
        "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
        "thetvdb_id": 121361,
        "tvrage_id": 24493,
        "type": "Scripted",
        "updated_at": "2024-11-15T09:12:41+00:00",
        "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
        "web_channel": null,
        "weight": 99
      },
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    }
  ],
  "matched": 1,
  "total_available": 31402
}

Get the streaming schedule

List the episodes released on streaming services on a given day. TVmaze separates services available in one country (Hulu, Sky Go) from global ones (Netflix, Prime Video); choose which you want with Scope. No API key required.

Inputs

Scopescopetext: Which services to include. Everywhere covers both local and global; Global only covers services like Netflix that are not tied to one country; One country covers only that country's own services.One of: all (Everywhere), global (Global services only), country (One country only). Default: all.
Country codecountrytext: ISO 3166-1 country code, for example US or GB. Required when Scope is One country only, ignored otherwise.
Datedatedate: The day to list, as YYYY-MM-DD. Defaults to today.

Outputs

countnumber: How many episodes were returned.
episodeslist: Episodes released that day, in release order.

Example output

{
  "count": 1,
  "episodes": [
    {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "show": {
        "average_runtime": 61,
        "ended": "2019-05-19",
        "genres": [
          "Drama",
          "Adventure",
          "Fantasy"
        ],
        "id": 82,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
        "imdb_id": "tt0944947",
        "language": "English",
        "name": "Game of Thrones",
        "network": {
          "country": {
            "code": "US",
            "name": "United States",
            "timezone": "America/New_York"
          },
          "id": 8,
          "name": "HBO"
        },
        "next_episode": null,
        "official_site": "http://www.hbo.com/game-of-thrones",
        "premiered": "2011-04-17",
        "previous_episode": {
          "id": 1623968,
          "name": "The Iron Throne",
          "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
        },
        "rating": 8.9,
        "runtime": 60,
        "schedule_days": [
          "Sunday"
        ],
        "schedule_time": "21:00",
        "status": "Ended",
        "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
        "thetvdb_id": 121361,
        "tvrage_id": 24493,
        "type": "Scripted",
        "updated_at": "2024-11-15T09:12:41+00:00",
        "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
        "web_channel": null,
        "weight": 99
      },
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    }
  ]
}

Get the TV schedule

List the TV episodes airing in a country on a given day, each with the show it belongs to. Covers broadcast and cable plus country-specific streaming; for Netflix and other global services use Get the streaming schedule. No API key required.

Inputs

Country codecountrytext: ISO 3166-1 country code, for example US, CA or AU. Defaults to US. Note the United Kingdom is GB, not UK.
Datedatedate: The day to list, as YYYY-MM-DD. Defaults to today.

Outputs

countnumber: How many episodes were returned.
episodeslist: Episodes airing that day, in the order they air.

Example output

{
  "count": 1,
  "episodes": [
    {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "show": {
        "average_runtime": 61,
        "ended": "2019-05-19",
        "genres": [
          "Drama",
          "Adventure",
          "Fantasy"
        ],
        "id": 82,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
        "imdb_id": "tt0944947",
        "language": "English",
        "name": "Game of Thrones",
        "network": {
          "country": {
            "code": "US",
            "name": "United States",
            "timezone": "America/New_York"
          },
          "id": 8,
          "name": "HBO"
        },
        "next_episode": null,
        "official_site": "http://www.hbo.com/game-of-thrones",
        "premiered": "2011-04-17",
        "previous_episode": {
          "id": 1623968,
          "name": "The Iron Throne",
          "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
        },
        "rating": 8.9,
        "runtime": 60,
        "schedule_days": [
          "Sunday"
        ],
        "schedule_time": "21:00",
        "status": "Ended",
        "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
        "thetvdb_id": 121361,
        "tvrage_id": 24493,
        "type": "Scripted",
        "updated_at": "2024-11-15T09:12:41+00:00",
        "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
        "web_channel": null,
        "weight": 99
      },
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    }
  ]
}

List all people

Read one page of every person in the TVmaze database, 1000 to a page. Paged by id exactly like List all shows, so the same resume rule applies. No API key required.

Inputs

Pagepagenumber: Which page to read, starting at 0. Page 3 holds people with ids 3000 to 3999.At least 0. Default: 0.
Limitlimitnumber: The most people to return from the page.From 1 to 1000. Default: 1000.

Outputs

countnumber: How many people were returned.
has_moretrue/false: False once a page comes back empty, which is TVmaze's signal that the index has been walked to its end.
pagenumber: The page that was read.
peoplelist: People on this page.

Example output

{
  "count": 1,
  "has_more": true,
  "page": 0,
  "people": [
    {
      "birthday": "1969-06-11",
      "country": {
        "code": "US",
        "name": "United States",
        "timezone": "America/New_York"
      },
      "deathday": null,
      "gender": "Male",
      "id": 29,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/863.jpg",
      "name": "Peter Dinklage",
      "url": "https://www.tvmaze.com/people/29/peter-dinklage"
    }
  ]
}

List all shows

Read one page of the whole TVmaze catalogue, 250 shows to a page, for building or refreshing a local copy. Pages are numbered by id, not position, so nothing shuffles between runs: resume at floor(last id / 250) and step forward until 'has more' is false. No API key required.

Inputs

Pagepagenumber: Which page to read, starting at 0. Page 3 holds shows with ids 750 to 999.At least 0. Default: 0.
Limitlimitnumber: The most shows to return from the page.From 1 to 1000. Default: 250.

Outputs

countnumber: How many shows were returned.
has_moretrue/false: False once a page comes back empty, which is TVmaze's signal that the index has been walked to its end.
pagenumber: The page that was read.
showslist: Shows on this page.

Example output

{
  "count": 1,
  "has_more": true,
  "page": 0,
  "shows": [
    {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    }
  ]
}

List marked episodes

List the episodes marked on your TVmaze account. Narrow it to one show with Show ID; without that it is every episode you have ever marked, which on a long-standing account is thousands. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Show IDshow_idnumber: Only return marked episodes of this show. Leave empty for every show.

Outputs

countnumber: How many episodes were returned.
episodeslist: Marked episodes.

Example output

{
  "count": 1,
  "episodes": [
    {
      "episode": {
        "airdate": "2011-04-17",
        "airstamp": "2011-04-18T01:00:00+00:00",
        "airtime": "21:00",
        "id": 4952,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
        "name": "Winter is Coming",
        "number": 1,
        "rating": 8.4,
        "runtime": 60,
        "season": 1,
        "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
        "type": "regular",
        "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
      },
      "episode_id": 4952,
      "marked_at": "2024-03-02T20:14:00+00:00",
      "marked_timestamp": 1709410440,
      "type": 0,
      "type_label": "watched"
    }
  ]
}

List marked episodes for a show

List what you have marked for one show: watched, acquired, skipped, or all three. This is the version of the marked-episode list that works without Premium, which is why it takes a show rather than offering the lot. Needs your TVmaze username and API key. Premium is not required for this one.

Inputs

Show IDshow_idnumberRequired: The TVmaze id of the show, for example 82.
Only this kindmark_typetext: Leave empty for every kind of mark.One of: watched, acquired, skipped.

Outputs

countnumber: How many episodes were returned.
episodeslist: Marked episodes of this show.

Example output

{
  "count": 1,
  "episodes": [
    {
      "episode": {
        "airdate": "2011-04-17",
        "airstamp": "2011-04-18T01:00:00+00:00",
        "airtime": "21:00",
        "id": 4952,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
        "name": "Winter is Coming",
        "number": 1,
        "rating": 8.4,
        "runtime": 60,
        "season": 1,
        "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
        "type": "regular",
        "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
      },
      "episode_id": 4952,
      "marked_at": "2024-03-02T20:14:00+00:00",
      "marked_timestamp": 1709410440,
      "type": 0,
      "type_label": "watched"
    }
  ]
}

List shows under a tag

List the shows filed under one of your TVmaze tags, each in full rather than as a bare id. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Tag IDtag_idnumberRequired: The TVmaze id of the tag, from List tags.

Outputs

countnumber: How many shows were returned.
showslist: Shows under this tag.
tag_idnumber: The tag that was read.

Example output

{
  "count": 1,
  "shows": [
    {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    }
  ],
  "tag_id": 417
}

List the tags on your TVmaze account. Tags are your own labels for grouping shows. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

None.

Outputs

countnumber: How many tags were returned.
tagslist: Your tags.

Example output

{
  "count": 1,
  "tags": [
    {
      "id": 417,
      "name": "Watching with the kids"
    }
  ]
}

List what you follow

List the shows, people, networks or streaming services your TVmaze account follows. Each row comes back with the name and the full record, not just an id, so it can be used or reported directly. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingfollow_typetext: What is being followed. TVmaze keeps a separate list for each kind, so this decides which list is read or written.One of: show, person, network, webchannel (Streaming service). Default: show.

Outputs

countnumber: How many items were returned.
followslist: What this account follows.
typetext: Which kind of list was read.

Example output

{
  "count": 1,
  "follows": [
    {
      "details": {
        "average_runtime": 61,
        "ended": "2019-05-19",
        "genres": [
          "Drama",
          "Adventure",
          "Fantasy"
        ],
        "id": 82,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
        "imdb_id": "tt0944947",
        "language": "English",
        "name": "Game of Thrones",
        "network": {
          "country": {
            "code": "US",
            "name": "United States",
            "timezone": "America/New_York"
          },
          "id": 8,
          "name": "HBO"
        },
        "next_episode": null,
        "official_site": "http://www.hbo.com/game-of-thrones",
        "premiered": "2011-04-17",
        "previous_episode": {
          "id": 1623968,
          "name": "The Iron Throne",
          "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
        },
        "rating": 8.9,
        "runtime": 60,
        "schedule_days": [
          "Sunday"
        ],
        "schedule_time": "21:00",
        "status": "Ended",
        "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
        "thetvdb_id": 121361,
        "tvrage_id": 24493,
        "type": "Scripted",
        "updated_at": "2024-11-15T09:12:41+00:00",
        "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
        "web_channel": null,
        "weight": 99
      },
      "id": 82,
      "name": "Game of Thrones",
      "type": "show",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones"
    }
  ],
  "type": "show"
}

List your votes

List the votes your TVmaze account has cast, on shows or on episodes. Show votes come back with the show attached; episode votes carry the episode id only, which is TVmaze's own limit. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingvote_typetext: Whether the vote is on a show or on a single episode.One of: show, episode. Default: show.

Outputs

countnumber: How many votes were returned.
typetext: Which list was read.
voteslist: Votes cast by this account.

Example output

{
  "count": 1,
  "type": "show",
  "votes": [
    {
      "details": {
        "average_runtime": 61,
        "ended": "2019-05-19",
        "genres": [
          "Drama",
          "Adventure",
          "Fantasy"
        ],
        "id": 82,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
        "imdb_id": "tt0944947",
        "language": "English",
        "name": "Game of Thrones",
        "network": {
          "country": {
            "code": "US",
            "name": "United States",
            "timezone": "America/New_York"
          },
          "id": 8,
          "name": "HBO"
        },
        "next_episode": null,
        "official_site": "http://www.hbo.com/game-of-thrones",
        "premiered": "2011-04-17",
        "previous_episode": {
          "id": 1623968,
          "name": "The Iron Throne",
          "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
        },
        "rating": 8.9,
        "runtime": 60,
        "schedule_days": [
          "Sunday"
        ],
        "schedule_time": "21:00",
        "status": "Ended",
        "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
        "thetvdb_id": 121361,
        "tvrage_id": 24493,
        "type": "Scripted",
        "updated_at": "2024-11-15T09:12:41+00:00",
        "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
        "web_channel": null,
        "weight": 99
      },
      "id": 82,
      "type": "show",
      "vote": 9,
      "voted_at": "2024-03-02T20:15:11+00:00",
      "voted_timestamp": 1709410511
    }
  ]
}

Look up a show by IMDb or TheTVDB id

Find a TVmaze show from its id on another service: IMDb, TheTVDB or TVRage. Use this to map a catalogue you already hold onto TVmaze without matching on names. Returns one show or none. No API key required.

Inputs

Which serviceexternal_sourcetext: Which service the id belongs to.One of: imdb, thetvdb, tvrage. Default: imdb.
ID on that serviceexternal_idtextRequired: The id on that service: an IMDb id looks like "tt0944947", a TheTVDB or TVRage id is a number like "81189".

Outputs

foundtrue/false: Whether TVmaze knows this external id.
showobject: The show, or null if the id is not mapped.

Example output

{
  "found": true,
  "show": {
    "average_runtime": 61,
    "ended": "2019-05-19",
    "genres": [
      "Drama",
      "Adventure",
      "Fantasy"
    ],
    "id": 82,
    "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
    "imdb_id": "tt0944947",
    "language": "English",
    "name": "Game of Thrones",
    "network": {
      "country": {
        "code": "US",
        "name": "United States",
        "timezone": "America/New_York"
      },
      "id": 8,
      "name": "HBO"
    },
    "next_episode": null,
    "official_site": "http://www.hbo.com/game-of-thrones",
    "premiered": "2011-04-17",
    "previous_episode": {
      "id": 1623968,
      "name": "The Iron Throne",
      "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
    },
    "rating": 8.9,
    "runtime": 60,
    "schedule_days": [
      "Sunday"
    ],
    "schedule_time": "21:00",
    "status": "Ended",
    "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
    "thetvdb_id": 121361,
    "tvrage_id": 24493,
    "type": "Scripted",
    "updated_at": "2024-11-15T09:12:41+00:00",
    "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
    "web_channel": null,
    "weight": 99
  }
}

Mark an episode

Mark an episode as watched, acquired or skipped on your TVmaze account. Needs your TVmaze username and API key. Premium is not required for this one.

Inputs

Episode IDepisode_idnumberRequired: The TVmaze id of the episode, for example 4952. Get one from a show's episode list or Get an episode by number.
Mark asmark_typetext: How to mark it. Acquired means you have the episode but have not watched it; skipped means you have decided not to.One of: watched, acquired, skipped. Default: watched.
Whenmarked_atdate and time: When you watched it. Accepts a date (2024-03-02), a full timestamp, or a Unix epoch. Leave empty to record it as now.

Outputs

episodeobject: The episode as it is now marked.

Example output

{
  "episode": {
    "episode": {
      "airdate": "2011-04-17",
      "airstamp": "2011-04-18T01:00:00+00:00",
      "airtime": "21:00",
      "id": 4952,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
      "name": "Winter is Coming",
      "number": 1,
      "rating": 8.4,
      "runtime": 60,
      "season": 1,
      "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
      "type": "regular",
      "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
    },
    "episode_id": 4952,
    "marked_at": "2024-03-02T20:14:00+00:00",
    "marked_timestamp": 1709410440,
    "type": 0,
    "type_label": "watched"
  }
}

Mark episodes of a show by number

Mark episodes of one show using season and episode numbers, or air dates, instead of TVmaze episode ids, and name the show by its TVmaze, TheTVDB or IMDb id. This is the action for importing a watch history from somewhere else, because nothing has to be resolved to a TVmaze id first. Needs your TVmaze username and API key. Premium is not required for this one.

Inputs

Show identified byshow_id_sourcetext: Which service the show id below belongs to.One of: tvmaze, thetvdb, imdb. Default: tvmaze.
Show IDshow_idtextRequired: The show's id on that service: 82 for TVmaze, or "tt0944947" for IMDb.
EpisodesepisodeslistRequired: The episodes to mark. Each needs either season and episode, or an airdate.
Mark asmark_typetext: How to mark it. Acquired means you have the episode but have not watched it; skipped means you have decided not to.One of: watched, acquired, skipped. Default: watched.
Whenmarked_atdate and time: When you watched it. Accepts a date (2024-03-02), a full timestamp, or a Unix epoch. Leave empty to record it as now.

Outputs

failedlist: The episodes TVmaze rejected, each with the reason. A partial success answers HTTP 207 and lands here rather than raising, so a workflow can retry or report the difference.
failed_countnumber: How many were rejected.
markedlist: The episodes TVmaze accepted.
marked_countnumber: How many were accepted.

Example output

{
  "failed": [
    {
      "code": 404,
      "input": {
        "episode": 1,
        "marked_at": 0,
        "season": 99,
        "type": 0
      },
      "message": "episode not found"
    }
  ],
  "failed_count": 1,
  "marked": [
    {
      "episode": {
        "airdate": "2011-04-17",
        "airstamp": "2011-04-18T01:00:00+00:00",
        "airtime": "21:00",
        "id": 4952,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
        "name": "Winter is Coming",
        "number": 1,
        "rating": 8.4,
        "runtime": 60,
        "season": 1,
        "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
        "type": "regular",
        "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
      },
      "episode_id": 4952,
      "marked_at": "2024-03-02T20:14:00+00:00",
      "marked_timestamp": 1709410440,
      "type": 0,
      "type_label": "watched"
    }
  ],
  "marked_count": 1
}

Mark many episodes

Mark a batch of episodes by their TVmaze episode ids in one request. TVmaze judges each entry separately, so the result splits into marked and failed rather than the whole batch succeeding or failing together; check 'failed count'. Needs your TVmaze username and API key. Premium is not required for this one.

Inputs

EpisodesepisodeslistRequired: The episodes to mark. Each needs an episode_id, and may override mark_type or marked_at for itself.
Mark asmark_typetext: How to mark it. Acquired means you have the episode but have not watched it; skipped means you have decided not to.One of: watched, acquired, skipped. Default: watched.
Whenmarked_atdate and time: When you watched it. Accepts a date (2024-03-02), a full timestamp, or a Unix epoch. Leave empty to record it as now.

Outputs

failedlist: The episodes TVmaze rejected, each with the reason. A partial success answers HTTP 207 and lands here rather than raising, so a workflow can retry or report the difference.
failed_countnumber: How many were rejected.
markedlist: The episodes TVmaze accepted.
marked_countnumber: How many were accepted.

Example output

{
  "failed": [],
  "failed_count": 0,
  "marked": [
    {
      "episode": {
        "airdate": "2011-04-17",
        "airstamp": "2011-04-18T01:00:00+00:00",
        "airtime": "21:00",
        "id": 4952,
        "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg",
        "name": "Winter is Coming",
        "number": 1,
        "rating": 8.4,
        "runtime": 60,
        "season": 1,
        "summary": "Lord Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
        "type": "regular",
        "url": "https://www.tvmaze.com/episodes/4952/game-of-thrones-1x01-winter-is-coming"
      },
      "episode_id": 4952,
      "marked_at": "2024-03-02T20:14:00+00:00",
      "marked_timestamp": 1709410440,
      "type": 0,
      "type_label": "watched"
    }
  ],
  "marked_count": 1
}

Poll a TVmaze authentication request

Check whether a user has confirmed an authentication request, and collect their API key once they have. Poll no faster than once every ten seconds. TVmaze hands the key over exactly once, so store it on the first success; polling again answers as expired. The key lands in this step's result and therefore in the run log: write it to a connection, not to a message or a sheet. Needs no credentials; this is how you obtain them.

Inputs

TokentokentextRequired: The token from Start a TVmaze authentication request.

Outputs

apikeytext: The user's API key, returned once and only once. Treat as a secret.
confirmedtrue/false: Whether the user has confirmed yet.
expiredtrue/false: True when the token is unknown: never issued, or already exchanged for a key. Stop polling.
usernametext: The TVmaze username the key belongs to.

Example output

{
  "apikey": "REDACTED-EXAMPLE-KEY",
  "confirmed": true,
  "expired": false,
  "username": "example_user"
}

Remove your vote

Remove your TVmaze vote from a show or an episode. Nothing to remove reports removed as false rather than failing. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingvote_typetext: Whether the vote is on a show or on a single episode.One of: show, episode. Default: show.
TVmaze IDitem_idnumberRequired: The TVmaze id of the show or episode.

Outputs

idnumber: The id that was acted on.
removedtrue/false: True if a vote was removed, false if there was none.
typetext: The kind that was acted on.

Example output

{
  "id": 82,
  "removed": true,
  "type": "show"
}

Rename a tag

Rename one of your TVmaze tags. The shows under it are untouched. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Tag IDtag_idnumberRequired: The TVmaze id of the tag, from List tags.
New namenametextRequired: What to rename it to.

Outputs

tagobject: The tag as it now stands.

Example output

{
  "tag": {
    "id": 417,
    "name": "Watching with the kids"
  }
}

Search people

Search TVmaze for actors and crew by name and get back each match with their id, country, birthday, and headshot. Use the id with the credit actions to see what they have worked on. No API key required.

Inputs

Search queryquerytextRequired: The person's name, for example "peter dinklage". TVmaze tolerates minor typos.

Outputs

countnumber: How many people were returned.
peoplelist: Matching people, most relevant first.

Example output

{
  "count": 1,
  "people": [
    {
      "birthday": "1969-06-11",
      "country": {
        "code": "US",
        "name": "United States",
        "timezone": "America/New_York"
      },
      "deathday": null,
      "gender": "Male",
      "id": 29,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/0/863.jpg",
      "name": "Peter Dinklage",
      "score": 0.9539776,
      "url": "https://www.tvmaze.com/people/29/peter-dinklage"
    }
  ]
}

Search shows

Search TVmaze for TV shows by name and get back each match with its id, network, genres, status, rating, and summary. Use the id with the other actions. No API key required.

Inputs

Search queryquerytextRequired: The show name to search for, for example "breaking bad". TVmaze tolerates minor typos.

Outputs

countnumber: How many shows were returned.
showslist: Matching shows, most relevant first.

Example output

{
  "count": 1,
  "shows": [
    {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "score": 0.9079084,
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    }
  ]
}

Start a TVmaze authentication request

Ask TVmaze to start authenticating a user by email, so you can get their API key without ever handling their password. TVmaze emails them a confirmation link; once they confirm, Poll an authentication request returns the key. Turn the email off to get a URL to send them to instead. Needs no credentials; this is how you obtain them.

Inputs

Email addressemailtextRequired: The email address of the TVmaze account.
Email a confirmation linkemail_confirmationtrue/false: On, TVmaze emails them a link. Off, use the returned confirm URL instead, only useful if they are already signed in to TVmaze on the device in front of them.Default: true.

Outputs

confirm_urltext: Where to send the user to confirm the request.
tokentext: Pass this to Poll an authentication request.

Example output

{
  "confirm_url": "https://www.tvmaze.com/auth/confirm/5f7e1c0a9b2d",
  "token": "5f7e1c0a9b2d4e3f8a6c1b0d9e8f7a6b"
}

Tag a show

File a show under one of your TVmaze tags. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Tag IDtag_idnumberRequired: The TVmaze id of the tag, from List tags.
Show IDshow_idnumberRequired: The TVmaze id of the show to tag.

Outputs

show_idnumber: The show tagged.
tag_idnumber: The tag used.
taggedtrue/false: Whether the show is now tagged.

Example output

{
  "show_id": 82,
  "tag_id": 417,
  "tagged": true
}

Unfollow something

Stop following a show, person, network or streaming service. Something that was not followed reports removed as false rather than failing. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingfollow_typetext: What is being followed. TVmaze keeps a separate list for each kind, so this decides which list is read or written.One of: show, person, network, webchannel (Streaming service). Default: show.
TVmaze IDitem_idnumberRequired: The TVmaze id of the show, person, network or streaming service to unfollow.

Outputs

idnumber: The id that was acted on.
removedtrue/false: True if a follow was removed, false if there was none. Either way it is not followed now.
typetext: The kind that was acted on.

Example output

{
  "id": 82,
  "removed": true,
  "type": "show"
}

Unmark an episode

Remove an episode's mark from your TVmaze account. An episode that was not marked reports removed as false rather than failing, so this is safe to run over a list. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Episode IDepisode_idnumberRequired: The TVmaze id of the episode to unmark.

Outputs

episode_idnumber: The episode acted on.
removedtrue/false: True if a mark was removed, false if there was none to remove. Either way the episode is now unmarked.

Example output

{
  "episode_id": 4952,
  "removed": true
}

Untag a show

Take a show out of one of your TVmaze tags. A show that was not tagged reports removed as false rather than failing. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

Tag IDtag_idnumberRequired: The TVmaze id of the tag, from List tags.
Show IDshow_idnumberRequired: The TVmaze id of the show to untag.

Outputs

removedtrue/false: True if the show was under the tag, false if it was not.
show_idnumber: The show acted on.
tag_idnumber: The tag acted on.

Example output

{
  "removed": true,
  "show_id": 82,
  "tag_id": 417
}

Vote for a show or episode

Cast a vote from 1 to 10 for a show or an episode on your TVmaze account. Voting again replaces your previous vote. Needs your TVmaze username and API key, and a TVmaze Premium subscription.

Inputs

What kind of thingvote_typetext: Whether the vote is on a show or on a single episode.One of: show, episode. Default: show.
TVmaze IDitem_idnumberRequired: The TVmaze id of the show or episode to vote for.
RatingvotenumberRequired: Your rating, a whole number from 1 to 10.From 1 to 10.
Whenvoted_atdate and time: When you voted for it. Accepts a date (2024-03-02), a full timestamp, or a Unix epoch. Leave empty to record it as now.

Outputs

typetext: The kind that was voted on.
voteobject: The vote as recorded.

Example output

{
  "type": "show",
  "vote": {
    "details": {
      "average_runtime": 61,
      "ended": "2019-05-19",
      "genres": [
        "Drama",
        "Adventure",
        "Fantasy"
      ],
      "id": 82,
      "image_url": "https://static.tvmaze.com/uploads/images/original_untouched/190/476117.jpg",
      "imdb_id": "tt0944947",
      "language": "English",
      "name": "Game of Thrones",
      "network": {
        "country": {
          "code": "US",
          "name": "United States",
          "timezone": "America/New_York"
        },
        "id": 8,
        "name": "HBO"
      },
      "next_episode": null,
      "official_site": "http://www.hbo.com/game-of-thrones",
      "premiered": "2011-04-17",
      "previous_episode": {
        "id": 1623968,
        "name": "The Iron Throne",
        "url": "https://www.tvmaze.com/episodes/1623968/game-of-thrones-8x06"
      },
      "rating": 8.9,
      "runtime": 60,
      "schedule_days": [
        "Sunday"
      ],
      "schedule_time": "21:00",
      "status": "Ended",
      "summary": "Based on the bestselling book series A Song of Ice and Fire by George R.R. Martin, this sprawling new HBO drama is set in a world where summers span decades and winters can last a lifetime.",
      "thetvdb_id": 121361,
      "tvrage_id": 24493,
      "type": "Scripted",
      "updated_at": "2024-11-15T09:12:41+00:00",
      "url": "https://www.tvmaze.com/shows/82/game-of-thrones",
      "web_channel": null,
      "weight": 99
    },
    "id": 82,
    "type": "show",
    "vote": 9,
    "voted_at": "2024-03-02T20:15:11+00:00",
    "voted_timestamp": 1709410511
  }
}

ActionsCopy Anchor Link

Check if an episode is markedCopy Anchor Link

Inputs

Outputs

Check if you follow somethingCopy Anchor Link

Inputs

Outputs

Check TVmaze credentialsCopy Anchor Link

Inputs

Outputs

Check your voteCopy Anchor Link

Inputs

Outputs

Create a tagCopy Anchor Link

Inputs

Outputs

Delete a tagCopy Anchor Link

Inputs

Outputs

Find one showCopy Anchor Link

Inputs

Outputs

Follow somethingCopy Anchor Link

Inputs

Outputs

Get a personCopy Anchor Link

Inputs

Outputs

Get a person's acting creditsCopy Anchor Link

Inputs

Outputs

Get a person's crew creditsCopy Anchor Link

Inputs

Outputs

Get a person's guest appearancesCopy Anchor Link

Inputs

Outputs

Get a season's episodesCopy Anchor Link

Inputs

Outputs

Get a showCopy Anchor Link

Inputs

Outputs

Get a show's alternate episode ordersCopy Anchor Link

Inputs

Outputs

Get a show's castCopy Anchor Link

Inputs

Outputs

Get a show's crewCopy Anchor Link

Inputs

Outputs

Get a show's episodesCopy Anchor Link

Inputs

Outputs

Get a show's episodes by dateCopy Anchor Link

Inputs

Outputs

Get a show's imagesCopy Anchor Link

Inputs

Outputs

Get a show's other titlesCopy Anchor Link

Inputs

Outputs

Get a show's seasonsCopy Anchor Link

Inputs

Outputs

Get an alternate episode orderCopy Anchor Link

Inputs

Outputs

Get an episodeCopy Anchor Link

Inputs

Outputs

Get an episode by numberCopy Anchor Link

Inputs

Outputs

Get an episode's guest castCopy Anchor Link

Inputs

Outputs

Actions

Check if an episode is marked

Check if you follow something

Check TVmaze credentials

Check your vote

Create a tag

Delete a tag

Find one show

Follow something

Get a person

Get a person's acting credits

Get a person's crew credits

Get a person's guest appearances

Get a season's episodes

Get a show

Get a show's alternate episode orders

Get a show's cast

Get a show's crew

Get a show's episodes

Get a show's episodes by date

Get a show's images

Get a show's other titles

Get a show's seasons

Get an alternate episode order

Get an episode

Get an episode by number

Get an episode's guest cast

Get an episode's guest crew

Get recently changed people

Get recently changed shows

Get the full future schedule

Get the streaming schedule

Get the TV schedule

List all people

List all shows

List marked episodes

List marked episodes for a show

List shows under a tag

List tags

List what you follow

List your votes

Look up a show by IMDb or TheTVDB id

Mark an episode

Mark episodes of a show by number

Mark many episodes

Poll a TVmaze authentication request

Remove your vote

Rename a tag

Search people

Search shows

Start a TVmaze authentication request