thetvdb_api

Release v0.3.1

thetvdb_api is a Python API for theTVDB.com. It is very simple to use and has a lot of features.

Features

This API allows you to access all the information of theTVDB.com including:

  • Informations about a tv show (such as first aired, network...)
  • Informations about an episode (such as director, writer...)
  • All the banners linked to a show
  • All the actors of a show

Usage

First of all, you will need an API key from theTVDB.com. You can easily get one from this registration page.

Get the show informations

There are 2 ways to create theTVDB object depending on the following situations:

  • you know in what language you want to retrieve the informations of the show. Be aware that all the shows are not available in all languages
  • you don’t know the language

You know the language

import thetvdb_api

thetvdb_api.set_cache('some folder') #set the cache folder
series = thetvdb_api.set_series('some show name', 'your tvdb api key', 'language')

series = thetvdb_api.get_series(series)

For example:

import thetvdb_api

thetvdb_api.set_cache('~/.cache')

series = thetvdb_api.set_series('The Office (US)', 'XXXXXXXXXXXXXXXX', 'en')
series_infos = thetvdb_api.get_series(series)

If set_cache() is not called, the result of the request won’t be cached. set_cache() accepts a second optional argument which is the time to hold cache in seconds (default is 21600)

Language must be one of the languages supported by theTVDB.com. See Available languages.

See get_series() for more information.

You don’t know the language

import thetvdb_api

thetvdb_api.set_cache('some folder') #set the cache folder
series = thetvdb_api.set_series('some show name', 'your tvdb api key')

series_infos = thetvdb_api.get_series(series )

For example:

import thetvdb_api

thetvdb_api.set_cache('~/.cache')
series = thetvdb_api.set_series('The Office (US)', 'XXXXXXXXXXXXXXXX')

series_infos = thetvdb_api.get_series(series)

See get_series() for more information.

You can later specify a language and get some more show information by doing:

thetvdb_api.set_language(series, 'en')
series_infos = thetvdb_api.get_series(series)

Get the episode informations

A language must have been set through the constructor or the set_language() function. Otherwise, English will be chosen but it can lead to unexpected output.

episode_infos = thetvdb_api.get_episode(series, 'season_number', 'episode_number')

For example:

episode_infos = thetvdb_api.get_episode(series, 3, 9)

get_episode() accepts a third argument ‘language’ if you want to specify a language different from the one defined in the constructor or the set_language() function.

See get_episode() for more information.

Get the banners

banners = thetvdb_api.get_banners(series)

See get_banners() for more information.

Get the actors

actors= thetvdb_api.get_actors(series)

See get_actors() for more information.

License

GNU General Public License v3 (GPLv3)

API Documentation

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

API

thetvdb_api.api.set_cache(path, period=21600)

Set the cache directory.

Parameters:
  • path (str) – path to the cache directory
  • period (int) – the period (in seconds) during which the cache is hold
Raises:

thetvdb_api.theTVDBError if unable to create the cache directory
thetvdb_api.api.set_series(series_name, api_key, language=None)

Search the series in theTVDB.com database.

Parameters:
  • series_name (str) – the name of the series
  • api_key (str) – the api key
  • language (str or None) – a language accepted by theTVDB.com (see Available languages) or None
Returns:

a thetvdb_api.theTVDB object to pass as argument to the other api functions
Return type:

thetvdb_api.theTVDB object
Raises:

thetvdb_api.theTVDBError if something went wrong
thetvdb_api.api.set_language(series, language)

Set the language to use.

Parameters:
  • series (thetvdb_api.theTVDB object) – the series created with set_series()
  • language (str) – a language accepted by theTVDB.com (see Available languages)
thetvdb_api.api.get_series(series)

Get the series informations.

Parameters:series – the series created with set_series()
Returns:a dictionary of all the series informations provided by theTVDB.com.
Return type:dict
Raises:thetvdb_api.theTVDBError if something went wrong

For more details about the output of the function, see Series.

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

For more details about the output of the function, see Episode.

thetvdb_api.api.get_banners(series)

Get all the banners of the series.

Parameters:series – the series created with set_series()
Returns:a dictionary of all the banners of the series provided by theTVDB.com.
Return type:dict
Raises:thetvdb_api.theTVDBError if something went wrong

For more details about the output of the function, see Banners.

thetvdb_api.api.get_actors(series)

Get all the actors of the series.

Parameters:series – the series created with set_series()
Returns:a dictionary of all the actors of the series provided by theTVDB.com.
Return type:dict
Raises:thetvdb_api.theTVDBError if something went wrong

For more details about the output of the function, see Actors.

Series

thetvdb_api.api.get_series(series)

Get the series informations.

Parameters:series – the series created with set_series()
Returns:a dictionary of all the series informations provided by theTVDB.com.
Return type:dict
Raises:thetvdb_api.theTVDBError if something went wrong

The get_series() function returns a dictionary with the following keys (some are only available if you have specified a language in set_series() or with the set_language() function):

  • seriesid: an unsigned integer that the unique identifier of the series. Cannot be null.
  • id: same as :mod:`seriesid*. Cannot be null.
  • language: a two digit string indicating the language. Cannot be null.
  • SeriesName: a string containing the series name in the language you requested. Will return the English name if no translation is found in the language requested. Can be null if the name isn’t known in the requested language or English.
  • AliasNames: a pipe “|” delimited list of alias names if the series has any other names in that language. Can be null.
  • SeriesNameList: a list (a Python list) of all the names of the series (SeriesNames and AliasNames). Cannot be null.
  • banner: the relative path to the highest rated banner for this series. Can 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.
  • FirstAired: the first aired date for the series in the “YYYY-MM-DD” format. Can be null.
  • IMDB_ID: the IMDB id for the series if known. Can be null.
  • zap2it_id: the zap2it ID if known. Can be null.
  • Network: the Network name if known. Can be null.

The parameters below are only available if a language has been specified:

  • Actors: a pipe delimited string of actors in plain text. Begins and ends with a pipe even if no actors are listed. Cannot be null.
  • ActorsList: same as Actors but in Python List format. Cannot be null.
  • Airs_DayOfWeek: the full name in English for the day of the week the series airs in plain text. Can be null.
  • Airs_Time: a string indicating the time of day the series airs on its original network. Format “HH:MM AM/PM”. Can be null.
  • ContentRating: the rating given to the series based on the US rating system. Can be null or a 4-5 character string.
  • Genre: a pipe delimited list of genres in plain text. Begins and ends with a | but may also be null.
  • GenreList: same as Genre but in Python List format. Cannot 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.
  • Runtime: an unsigned integer representing the runtime of the series in minutes. Can be null.
  • Status: a string containing either “Ended” or “Continuing”. Can be null.
  • added: a string containing the date/time the series was added to theTVDB.com in the format “YYYY-MM-DD HH:MM:SS” based on a 24 hour clock. Is null for older series.
  • addedBy: an unsigned integer. The ID of the theTVDB user who added the series to our database. Is null for older series.
  • fanart: the highest voted fanart for the requested series. Can be null.
  • lastupdated: Unix time stamp indicating the last time any changes were made to the series. Can be null.
  • posters: the highest voted poster for the requested series. Can be null.

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

Banners

thetvdb_api.api.get_banners(series)

Get all the banners of the series.

Parameters:series – the series created with set_series()
Returns:a dictionary of all the banners of the series provided by theTVDB.com.
Return type:dict
Raises:thetvdb_api.theTVDBError if something went wrong

The get_banners() function returns a dictionary with one sub-dictionary for each banner of the series. These sub-dictionaries have the following keys:

  • BannerPath: the location of the artwork.
  • ThumbnailPath: used exactly the same way as BannerPath, only shows if BannerType is fanart.
  • VignettePath: used exactly the same way as BannerPath, only shows if BannerType is fanart.
  • BannerType: this can be poster, fanart, series or season.
  • BannerType2: for series banners it can be text, graphical, or blank. For season banners it can be season or seasonwide. For fanart it can be 1280x720 or 1920x1080. For poster it will always be 680x1000. Blank banners will leave the title and show logo off the banner. Text banners will show the series name as plain text in an Arial font. Graphical banners will show the series name in the show’s official font or will display the actual logo for the show. Season banners are the standard DVD cover format while wide season banners will be the same dimensions as the series banners.
  • Language: some banners list the series name in a foreign language. The language abbreviation will be listed here.
  • Season: if the banner is for a specific season, that season number will be listed here.
  • Rating: returns either null or a decimal with four decimal places. The rating the banner currently has on the site.
  • RatingCount: always returns an unsigned integer. Number of people who have rated the image.
  • SeriesName: this can be true or false. Only shows if BannerType is fanart. Indicates if the seriesname is included in the image or not.
  • Colors: returns either null or three RGB colors in decimal format and pipe delimited. These are colors the artist picked that go well with the image. In order they are Light Accent Color, Dark Accent Color and Neutral Midtone Color. It’s meant to be used if you want to write something over the image, it gives you a good idea of what colors may work and show up well. Only shows if BannerType is fanart.

Actors

thetvdb_api.api.get_actors(series)

Get all the actors of the series.

Parameters:series – the series created with set_series()
Returns:a dictionary of all the actors of the series provided by theTVDB.com.
Return type:dict
Raises:thetvdb_api.theTVDBError if something went wrong

The get_actors() function returns a dictionary with one sub-dictionary for each actor of the series. These sub-dictionaries have the following keys:

  • Image: The location of the artwork.
  • Name: The actors real name.
  • Role: The name of the actors character in the series.
  • SortOrder: An integer from 0-3. 1 being the most important actor on the show and 3 being the third most important actor. 0 means they have no special sort order. Duplicates of 1-3 aren’t suppose to be allowed but currently are so the field isn’t perfect but can still be used for basic sorting.

Available languages

Available languages are the following:

  • English: en
  • Svenska: sv
  • Norsk: no
  • Dansk: da
  • Suomeksi: fi
  • Nederlands: nl
  • Deutsch: de
  • Italiano: it
  • Español: es
  • Français: fr
  • Polski: pl
  • Magyar: hu
  • Greek: el
  • Turkish: tr
  • Russian: ru
  • Hebrew: he
  • Japanese: ja
  • Portuguese: pt
  • Chinese: zh
  • Czech: cs
  • Slovenian: sl
  • Croatian: hr
  • Korean: ko

Changelog

0.3.0

release date: not released

  • Better naming convention (no backward incompatibility, only in core, not in api)
  • new doc
  • python3 support

0.2.0

release date: 2014-02-04

  • Change the name of the program: theTVDB API becomes thetvdb_api
  • Change the name of some functions : get_series_infos() become get_series() and get_episode_infos() become get_episodes()
  • set_cache() has more options: second argument is optional and tells how long the cache must be hold

0.1.0

release date: 2014-02-02

  • Initial release