EpisodeΒΆ

thetvdb_api.api.get_episode(series, episode_season, episode_number, language=None)

Get an episode informations.

Parameters:
  • series – the series created with set_series()
  • episode_season (int or str) – the number of the season
  • episode_number (int or str) – the number of the episode in the season
  • language (str or None) – a language accepted by theTVDB.com (see Available languages)
Returns:

a dictionary of all the episode informations provided by theTVDB.com.
Return type:

dict
Raises:

thetvdb_api.theTVDBError if something went wrong

The get_episode() function returns a dictionary with the following keys:

  • id: an unsigned integer assigned by theTVDB.com to the episode. Cannot be null.
  • Combined_episodenumber: an unsigned integer or decimal. Cannot be null. This returns the value of DVD_episodenumber if that field is not null. Otherwise it returns the value from EpisodeNumber. The field can be used as a simple way of prioritizing DVD order over aired order in your program. In general it’s best to avoid using this field as you can accomplish the same task locally and have more control if you use the DVD_episodenumber and EpisodeNumber fields separately.
  • Combined_season: an unsigned integer or decimal. Cannot be null. This returns the value of DVD_season if that field is not null. Otherwise it returns the value from SeasonNumber. The field can be used as a simple way of prioritizing DVD order over aired order in your program. In general it’s best to avoid using this field as you can accomplish the same task locally and have more control if you use the DVD_season and SeasonNumber fields separately.
  • DVD_episodenumber: a decimal with one decimal and can be used to join episodes together. Can be null, usually used to join episodes that aired as two episodes but were released on DVD as a single episode. If you see an episode 1.1 and 1.2 that means both records should be combined to make episode 1. Cartoons are also known to combine up to 9 episodes together, for example Animaniacs season two.
  • DVD_season: an unsigned integer indicating the season the episode was in according to the DVD release. Usually is the same as EpisodeNumber but can be different.
  • Director: a pipe delimited string of directors in plain text. Can be null.
  • DirectorStarsList: same as Director but in Python List format. Can be null.
  • EpImgFlag: an unsigned integer from 1-6.
    1. 4:3 - Indicates an image is a proper 4:3 (1.31 to 1.35) aspect ratio.
    2. 16:9 - Indicates an image is a proper 16:9 (1.739 to 1.818) aspect ratio.
    3. Invalid Aspect Ratio - Indicates anything not in a 4:3 or 16:9 ratio. We don’t bother listing any other non standard ratios.
    4. Image too Small - Just means the image is smaller then 300x170.
    5. Black Bars - Indicates there are black bars along one or all four sides of the image.
    6. Improper Action Shot - Could mean a number of things, usually used when someone uploads a promotional picture that isn’t actually from that episode but does refrence the episode, it could also mean it’s a credit shot or that there is writting all over it. It’s rarely used since most times an image would just be outright deleted if it falls in this category.
  • EpisodeName: a string containing the episode name in the language requested. Will return the English name if no translation is available in the language requested.
  • EpisodeNumber: an unsigned integer representing the episode number in its season according to the aired order. Cannot be null.
  • FirstAired: a string containing the date the series first aired in plain text using the format “YYYY-MM-DD”. Can be null.
  • GuestStars: a pipe delimited string of guest stars in plain text. Can be null.
  • GuestStarsList: same as GuestStars but in Python List format. Can be null.
  • IMDB_ID: an alphanumeric string containing the IMDB ID for the series. Can be null.
  • Language: a two character string indicating the language in accordance with ISO-639-1. Cannot be null.
  • Overview: a string containing the overview in the language requested. Will return the English overview if no translation is available in the language requested. Can be null.
  • ProductionCode: an alphanumeric string. Can be null.
  • Rating: The average rating users of theTVDB.com have rated the series out of 10, rounded to 1 decimal place. Can be null.
  • RatingCount: an unsigned integer representing the number of users who have rated the series. Can be null.
  • SeasonNumber: an unsigned integer representing the season number for the episode according to the aired order. Cannot be null.
  • Writer: a pipe delimited string of writers in plain text. Can be null.
  • WriterList: same as Writer but in Python List format. Can be null.
  • absolute_number: an unsigned integer. Can be null. Indicates the absolute episode number and completely ignores seasons. In others words a series with 20 episodes per season will have Season 3 episode 10 listed as 50. The field is mostly used with cartoons and anime series as they may have ambiguous seasons making it easier to use this field.
  • airsafter_season: an unsigned integer indicating the season number this episode comes after. This field is only available for special episodes. Can be null.
  • airsbefore_episode: an unsigned integer indicating the episode number this special episode airs before. Must be used in conjunction with airsbefore_season, do not with airsafter_season. This field is only available for special episodes. Can be null.
  • airsbefore_season: an unsigned integer indicating the season number this special episode airs before. Should be used in conjunction with airsbefore_episode for exact placement. This field is only available for special episodes. Can be null.
  • filename: The location of the episode image. Can be null.
  • lastupdated: Unix time stamp indicating the last time any changes were made to the episode. Can be null.
  • seasonid: an unsigned integer assigned by theTVDB.com to the season. Cannot be null.
  • seriesid: an unsigned integer assigned by theTVDB.com to the series. It does not change and will always represent the same series. Cannot be null.
  • thumb_added: a string containing the time the episode image was added to theTVDB.com in the format “YYYY-MM-DD HH:MM:SS” based on a 24 hour clock. Can be null.
  • thumb_height: an unsigned integer that represents the height of the episode image in pixels. Can be null
  • thumb_width: an unsigned integer that represents the width of the episode image in pixels. Can be null