# 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. App · Film, TV & Fandom · 55 actions. Web page: https://docs.lodol.com/docs/integrations/tvmaze ## Actions ### 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 ID (`episode_id`, number, required): The TVmaze id of the episode to check. **Outputs** - `episode` (object): The mark, or null if there is none. - `marked` (true/false): Whether the episode is marked at all. **Example output** ```json { "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 thing (`follow_type`, text): 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 ID (`item_id`, number, required): The TVmaze id of the show, person, network or streaming service to check. **Outputs** - `follow` (object): The follow record, or null if not followed. - `followed` (true/false): Whether this account follows it. - `id` (number): The id that was checked. - `type` (text): The kind that was checked. **Example output** ```json { "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_premium` (true/false): Whether the premium-only actions will work. - `premium` (number): The account's premium level. 0 means none. - `valid` (true/false): Whether TVmaze accepted the username and key. **Example output** ```json { "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 thing (`vote_type`, text): Whether the vote is on a show or on a single episode. One of: `show`, `episode`. Default: `show`. - TVmaze ID (`item_id`, number, required): The TVmaze id of the show or episode to check. **Outputs** - `id` (number): The id that was checked. - `type` (text): The kind that was checked. - `vote` (object): The vote, or null if there is none. - `voted` (true/false): Whether a vote exists. **Example output** ```json { "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 name (`name`, text, required): What to call it, for example "Watching with the kids". **Outputs** - `tag` (object): The tag that was created. **Example output** ```json { "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 ID (`tag_id`, number, required): The TVmaze id of the tag, from List tags. **Outputs** - `deleted` (true/false): True if a tag was deleted, false if there was no such tag. - `tag_id` (number): The tag acted on. **Example output** ```json { "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 name (`query`, text, required): The show name, for example "game of thrones". Small typos are tolerated, though less than in Search shows. **Outputs** - `found` (true/false): Whether TVmaze matched the name to a show. - `show` (object): The show, or null if nothing matched. **Example output** ```json { "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 thing (`follow_type`, text): 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 ID (`item_id`, number, required): The TVmaze id of the show, person, network or streaming service to follow. **Outputs** - `follow` (object): What is now followed. - `type` (text): The kind that was followed. **Example output** ```json { "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 ID (`person_id`, number, required): The TVmaze id of the person, for example 29. Search people first if you only have the name. **Outputs** - `person` (object): The person's details. **Example output** ```json { "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 ID (`person_id`, number, required): The TVmaze id of the person, for example 29. Search people first if you only have the name. **Outputs** - `count` (number): How many credits were returned. - `credits` (list): Shows they were cast in. **Example output** ```json { "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 ID (`person_id`, number, required): The TVmaze id of the person, for example 29. Search people first if you only have the name. **Outputs** - `count` (number): How many credits were returned. - `credits` (list): Shows they crewed on. **Example output** ```json { "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 ID (`person_id`, number, required): The TVmaze id of the person, for example 29. Search people first if you only have the name. **Outputs** - `count` (number): How many credits were returned. - `credits` (list): Episodes they guested in. **Example output** ```json { "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 ID (`season_id`, number, required): The TVmaze id of the season, for example 249. Get one from Get a show's seasons. - Include guest cast (`include_guest_cast`, true/false): Add each episode's guest cast to the result. One extra request in total rather than one per episode. Default: `false`. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): The season's episodes, in airing order. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. **Outputs** - `show` (object): The show's details. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. **Outputs** - `alternate_lists` (list): The show's alternate orderings. - `count` (number): How many lists were returned. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. **Outputs** - `cast` (list): Cast members, most prominent first. - `count` (number): How many cast members were returned. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. **Outputs** - `count` (number): How many crew members were returned. - `crew` (list): Crew members. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. - Include specials (`include_specials`, true/false): Include specials in the list. Off by default, which is what keeps season and episode numbering contiguous. Default: `false`. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): The show's episodes, in airing order. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. - Date (`date`, date, required): The air date to look for, as YYYY-MM-DD. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): Episodes that aired on that date. Empty if none did. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. - Image type (`image_type`, text): Keep only images of one kind. One of: `all` (All types), `poster`, `banner`, `background`, `typography`. Default: `all`. **Outputs** - `count` (number): How many images were returned. - `images` (list): The show's images. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. **Outputs** - `akas` (list): Alternative titles. - `count` (number): How many titles were returned. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. **Outputs** - `count` (number): How many seasons were returned. - `seasons` (list): The show's seasons, in order. **Example output** ```json { "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 ID (`alternate_list_id`, number, required): The id of the alternate list, from Get a show's alternate episode orders. **Outputs** - `alternate_episodes` (list): Episodes in this ordering, each with the canonical episode. - `count` (number): How many episodes were returned. **Example output** ```json { "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 ID (`episode_id`, number, required): 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** - `episode` (object): The episode, with its show. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. Search shows first if you only have the name. - Season number (`season`, number, required): The season number, for example 1. - Episode number (`number`, number, required): The episode number within that season, for example 1. **Outputs** - `episode` (object): The episode, or null if there is no such episode. - `found` (true/false): Whether that season and episode number exists. **Example output** ```json { "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 ID (`episode_id`, number, required): 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** - `count` (number): How many guest cast members were returned. - `guest_cast` (list): Guest cast for this episode. **Example output** ```json { "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 ID (`episode_id`, number, required): 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** - `count` (number): How many guest crew members were returned. - `guest_crew` (list): Guest crew for this episode. **Example output** ```json { "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 within (`since`, text): 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`. - Limit (`limit`, number): The most people to return, most recently changed first. From 1 to 1000. Default: `100`. **Outputs** - `count` (number): How many people were returned. - `since` (text): The window that was asked for. - `total_available` (number): How many people changed in that window. Larger than count means the limit trimmed the result. - `updates` (list): Changed people, most recent first. **Example output** ```json { "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 within (`since`, text): 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`. - Limit (`limit`, number): The most shows to return, most recently changed first. From 1 to 1000. Default: `100`. **Outputs** - `count` (number): How many shows were returned. - `since` (text): The window that was asked for. - `total_available` (number): How many shows changed in that window. Larger than count means the limit trimmed the result. - `updates` (list): Changed shows, most recent first. **Example output** ```json { "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 code (`country`, text): Keep only episodes airing in this country, for example GB. Leave empty for every country. - From date (`date_from`, date): Keep only episodes airing on or after this date. - To date (`date_to`, date): Keep only episodes airing on or before this date. - Limit (`limit`, number): The most episodes to return, soonest first. From 1 to 1000. Default: `100`. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): Matching episodes, soonest first, up to the limit. - `matched` (number): How many episodes matched the filters. Larger than count means the limit trimmed the result. - `total_available` (number): How many future episodes TVmaze holds in total. **Example output** ```json { "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** - Scope (`scope`, text): 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 code (`country`, text): ISO 3166-1 country code, for example US or GB. Required when Scope is One country only, ignored otherwise. - Date (`date`, date): The day to list, as YYYY-MM-DD. Defaults to today. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): Episodes released that day, in release order. **Example output** ```json { "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 code (`country`, text): ISO 3166-1 country code, for example US, CA or AU. Defaults to US. Note the United Kingdom is GB, not UK. - Date (`date`, date): The day to list, as YYYY-MM-DD. Defaults to today. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): Episodes airing that day, in the order they air. **Example output** ```json { "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** - Page (`page`, number): Which page to read, starting at 0. Page 3 holds people with ids 3000 to 3999. At least 0. Default: `0`. - Limit (`limit`, number): The most people to return from the page. From 1 to 1000. Default: `1000`. **Outputs** - `count` (number): How many people were returned. - `has_more` (true/false): False once a page comes back empty, which is TVmaze's signal that the index has been walked to its end. - `page` (number): The page that was read. - `people` (list): People on this page. **Example output** ```json { "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** - Page (`page`, number): Which page to read, starting at 0. Page 3 holds shows with ids 750 to 999. At least 0. Default: `0`. - Limit (`limit`, number): The most shows to return from the page. From 1 to 1000. Default: `250`. **Outputs** - `count` (number): How many shows were returned. - `has_more` (true/false): False once a page comes back empty, which is TVmaze's signal that the index has been walked to its end. - `page` (number): The page that was read. - `shows` (list): Shows on this page. **Example output** ```json { "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 ID (`show_id`, number): Only return marked episodes of this show. Leave empty for every show. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): Marked episodes. **Example output** ```json { "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 ID (`show_id`, number, required): The TVmaze id of the show, for example 82. - Only this kind (`mark_type`, text): Leave empty for every kind of mark. One of: `watched`, `acquired`, `skipped`. **Outputs** - `count` (number): How many episodes were returned. - `episodes` (list): Marked episodes of this show. **Example output** ```json { "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 ID (`tag_id`, number, required): The TVmaze id of the tag, from List tags. **Outputs** - `count` (number): How many shows were returned. - `shows` (list): Shows under this tag. - `tag_id` (number): The tag that was read. **Example output** ```json { "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 tags 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** - `count` (number): How many tags were returned. - `tags` (list): Your tags. **Example output** ```json { "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 thing (`follow_type`, text): 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** - `count` (number): How many items were returned. - `follows` (list): What this account follows. - `type` (text): Which kind of list was read. **Example output** ```json { "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 thing (`vote_type`, text): Whether the vote is on a show or on a single episode. One of: `show`, `episode`. Default: `show`. **Outputs** - `count` (number): How many votes were returned. - `type` (text): Which list was read. - `votes` (list): Votes cast by this account. **Example output** ```json { "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 service (`external_source`, text): Which service the id belongs to. One of: `imdb`, `thetvdb`, `tvrage`. Default: `imdb`. - ID on that service (`external_id`, text, required): The id on that service: an IMDb id looks like "tt0944947", a TheTVDB or TVRage id is a number like "81189". **Outputs** - `found` (true/false): Whether TVmaze knows this external id. - `show` (object): The show, or null if the id is not mapped. **Example output** ```json { "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 ID (`episode_id`, number, required): The TVmaze id of the episode, for example 4952. Get one from a show's episode list or Get an episode by number. - Mark as (`mark_type`, text): 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`. - When (`marked_at`, date 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** - `episode` (object): The episode as it is now marked. **Example output** ```json { "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 by (`show_id_source`, text): Which service the show id below belongs to. One of: `tvmaze`, `thetvdb`, `imdb`. Default: `tvmaze`. - Show ID (`show_id`, text, required): The show's id on that service: 82 for TVmaze, or "tt0944947" for IMDb. - Episodes (`episodes`, list, required): The episodes to mark. Each needs either season and episode, or an airdate. - Mark as (`mark_type`, text): 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`. - When (`marked_at`, date 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** - `failed` (list): 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_count` (number): How many were rejected. - `marked` (list): The episodes TVmaze accepted. - `marked_count` (number): How many were accepted. **Example output** ```json { "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** - Episodes (`episodes`, list, required): The episodes to mark. Each needs an episode_id, and may override mark_type or marked_at for itself. - Mark as (`mark_type`, text): 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`. - When (`marked_at`, date 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** - `failed` (list): 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_count` (number): How many were rejected. - `marked` (list): The episodes TVmaze accepted. - `marked_count` (number): How many were accepted. **Example output** ```json { "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** - Token (`token`, text, required): The token from Start a TVmaze authentication request. **Outputs** - `apikey` (text): The user's API key, returned once and only once. Treat as a secret. - `confirmed` (true/false): Whether the user has confirmed yet. - `expired` (true/false): True when the token is unknown: never issued, or already exchanged for a key. Stop polling. - `username` (text): The TVmaze username the key belongs to. **Example output** ```json { "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 thing (`vote_type`, text): Whether the vote is on a show or on a single episode. One of: `show`, `episode`. Default: `show`. - TVmaze ID (`item_id`, number, required): The TVmaze id of the show or episode. **Outputs** - `id` (number): The id that was acted on. - `removed` (true/false): True if a vote was removed, false if there was none. - `type` (text): The kind that was acted on. **Example output** ```json { "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 ID (`tag_id`, number, required): The TVmaze id of the tag, from List tags. - New name (`name`, text, required): What to rename it to. **Outputs** - `tag` (object): The tag as it now stands. **Example output** ```json { "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 query (`query`, text, required): The person's name, for example "peter dinklage". TVmaze tolerates minor typos. **Outputs** - `count` (number): How many people were returned. - `people` (list): Matching people, most relevant first. **Example output** ```json { "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 query (`query`, text, required): The show name to search for, for example "breaking bad". TVmaze tolerates minor typos. **Outputs** - `count` (number): How many shows were returned. - `shows` (list): Matching shows, most relevant first. **Example output** ```json { "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 address (`email`, text, required): The email address of the TVmaze account. - Email a confirmation link (`email_confirmation`, true/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_url` (text): Where to send the user to confirm the request. - `token` (text): Pass this to Poll an authentication request. **Example output** ```json { "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 ID (`tag_id`, number, required): The TVmaze id of the tag, from List tags. - Show ID (`show_id`, number, required): The TVmaze id of the show to tag. **Outputs** - `show_id` (number): The show tagged. - `tag_id` (number): The tag used. - `tagged` (true/false): Whether the show is now tagged. **Example output** ```json { "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 thing (`follow_type`, text): 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 ID (`item_id`, number, required): The TVmaze id of the show, person, network or streaming service to unfollow. **Outputs** - `id` (number): The id that was acted on. - `removed` (true/false): True if a follow was removed, false if there was none. Either way it is not followed now. - `type` (text): The kind that was acted on. **Example output** ```json { "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 ID (`episode_id`, number, required): The TVmaze id of the episode to unmark. **Outputs** - `episode_id` (number): The episode acted on. - `removed` (true/false): True if a mark was removed, false if there was none to remove. Either way the episode is now unmarked. **Example output** ```json { "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 ID (`tag_id`, number, required): The TVmaze id of the tag, from List tags. - Show ID (`show_id`, number, required): The TVmaze id of the show to untag. **Outputs** - `removed` (true/false): True if the show was under the tag, false if it was not. - `show_id` (number): The show acted on. - `tag_id` (number): The tag acted on. **Example output** ```json { "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 thing (`vote_type`, text): Whether the vote is on a show or on a single episode. One of: `show`, `episode`. Default: `show`. - TVmaze ID (`item_id`, number, required): The TVmaze id of the show or episode to vote for. - Rating (`vote`, number, required): Your rating, a whole number from 1 to 10. From 1 to 10. - When (`voted_at`, date 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** - `type` (text): The kind that was voted on. - `vote` (object): The vote as recorded. **Example output** ```json { "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 } } ```