TVDB::API - API to www.thetvdb.com
use TVDB::API; my $tvdb = TVDB::API::new([[$apikey], $language]); $tvdb->setApiKey($apikey); $tvdb->setLang('en'); $tvdb->setUserAgent("TVDB::API/$VERSION"); $tvdb->setBannerPath("/foo/bar/banners"); $tvdb->setCacheDB("$ENV{HOME}/.tvdb.db"); my $hashref = $tvdb->getConf(); my $value = $tvdb->getConf($key); $tvdb->setConf($key, $value); $tvdb->setConf({key1=>'value1', key2=>'value2'}); my $hashref = $tvdb->getAvailableMirrors([$nocache]); $tvdb->setMirrors($mirror, [$banner, [$zip]]); $tvdb->chooseMirrors([$nocache]); $tvdb->getAvailableLanguages([$nocache]); $tvdb->getUpdates([$period]); my $series_id = $tvdb->getPossibleSeriesId($series_name, [$nocache]); my $series_id = $tvdb->getSeriesId($series_name, [$nocache]); my $name = $tvdb->getSeriesName($series_id, [$nocache]); my $hashref = $tvdb->getSeries($series_name, [$nocache]); my $hashref = $tvdb->getSeriesAll($series_name, [$nocache]); my $hashref = $tvdb->getSeriesActors($series_name, [$nocache]); my $hashref = $tvdb->getSeriesActorsSorted($series_name, [$nocache]); my $hashref = $tvdb->getSeriesBanners($series_name, $type, $type2, $value, [$nocache]); my $hashref = $tvdb->getSeriesInfo($series_name, key, [$nocache]); my $string = $tvdb->getSeriesBanner($series_name, [$buffer, [$nocache]]); my $string = $tvdb->getSeriesFanart($series_name, [$buffer, [$nocache]]); my $string = $tvdb->getSeriesPoster($series_name, [$buffer, [$nocache]]); my $string = $tvdb->getSeriesOverview($series_name, [$nocache]); my $path = $tvdb->getBanner($banner, [$buffer, [$nocache]]); my $int = $tvdb->getMaxSeason($series, [$nocache]); my $hashref = $tvdb->getSeason($series, $season, [$nocache]); my @picture_names = $tvdb->getSeasonBanners($series, $season, [$nocache]); my $string = $tvdb->getSeasonBanner($series, $season, [$buffer, [$nocache]]); my @picture_names = $tvdb->getSeasonBannersWide($series, $season, [$nocache]); my $string = $tvdb->getSeasonBannerWide($series, $season, [$buffer, [$nocache]]); my $int = $tvdb->getMaxEpisode($series, $season, [$nocache]); my $hashref = $tvdb->getEpisode($series, $season, $episode, [$nocache]); my $hashref = $tvdb->getEpisodeAbs($series, $absEpisode, [$nocache]); my $hashref = $tvdb->getEpisodeDVD($series, $DVDseason, $DVDepisode, [$nocache]); my $hashref = $tvdb->getEpisodeId($episodeid, [$nocache]); my $hashref = $tvdb->getEpisodeByAirDate($series, $airdate, [$nocache]); my $string = $tvdb->getEpisodeInfo($series, $season, $episode, $info, [$nocache]); my $string = $tvdb->getEpisodeBanner($series, $season, $episode, [$buffer, [$nocache]]); my $string = $tvdb->getEpisodeName($series, $season, $episode, [$nocache]); my $string = $tvdb->getEpisodeOverview($series, $season, $episode, [$nocache]); my $hashref = $tvdb->getRatingsForUser($userid, $series, [$nocache]); $tvdb->dumpCache();
This module provides an API to the TVDB database through the new published API.
Create a TVDB::API object using APIKEY and using a default language of LANGUAGE. Both these arguments are optional.
APIKEY
LANGUAGE
New can also be called with a hashref as the first argument.
$tvdb = TVDB::API::new({ apikey => $apikey, lang => 'en', cache => 'filename', banner => 'banner/path', useragent => 'My useragent' });
Set the APIKEY to be used to access the web api for thetvdb.com
Set the LANGUAGE to use when downloading data from thetvdb.com
Set the USERAGENT to be used when downloading information from thetvdb.com
USERAGENT
Set the path in which to save downloaded banner graphics files.
Set the name of the database file to be used to save data from thetvdb.com
Get the list of mirror sites available from thetvdb.com. It returns a hashref of arrays. If NOCACHE is non-zero, then the mirrors are downloaded again even if they are in the cache database already.
NOCACHE
Returns: { xml => @xml_mirrors, banner => @banner_mirrors, zip => @zip_mirrors, }
Set the mirror site(s) to be used to download tv info. If BANNER or ZIP or not specified, then MIRROR is used instead.
BANNER
ZIP
MIRROR
Choose a random mirror from the list of available mirrors. If NOCACHE is non-zero, then the mirrors are downloaded again even if they are in the cache database already.
Get configurable values by KEY. If no KEY is specified, a hashref of all values is returned.
KEY
Set configurable values by KEY/VALUE pair. If a hashref is passed in, all KEY/VALUE pairs in the hashref will be configured.
VALUE
maxSeason => 50, # Maximum allowed season maxEpisode => 50, # Maximum allowed episode minUpdateTime => 3600*6, # Used by getUpdate('now') minBannerTime => 3600*24*7, # Used by getBanner() minEpisodeTime => 3600*24*7, # Used by getEpisode()
Get a list of available languages, and return them in a hashref. If NOCACHE is non-zero, then the available languages are downloaded again even if they are in the cache database already.
Get appropriate updates (day/week/month/all) from thetvdb.com based on the specified PERIOD. It then downloads updates for series, episodes, and banners which have already been downloaded.
PERIOD
day
Get the updates for the last 24 hours (86400 seconds).
week
Get the updates for the last week (7 days, or 604800 seconds).
month
Get the updates for the last month (30 days, or 2592000 seconds).
all
Get all updates available.
now
Based on the last update performed, determine whether to do a day, week, month or all update.
guess
Like now, based on the last update performed; determine whether to do a day, week, month or all update. However, if the last update was performed in the last 6 hours (setable as minUpdateTime with setConf()), do nothing. This is the default PERIOD.
minUpdateTime
Get a list of possible series ids for SERIESNAME from thetvtb.com. This will return a hashref of possibilities.
SERIESNAME
Get the series id (an integer) for SERIESNAME from thetvtb.com. If NOCACHE is non-zero, then the series id is downloaded again even if it is in the cache database already.
Get the series name (a string) for SERIESID. If NOCACHE is non-zero, then the series name is downloaded again even if it is in the cache database already.
SERIESID
Get the series info for SERIESNAME from thetvtb.com, which is returned as a hashref. If NOCACHE is non-zero, then the series info is downloaded again even if it is in the cache database already.
Get the series info, and all episodes for SERIESNAME from thetvtb.com, which is returned as a hashref. If NOCACHE is non-zero, then the series info and episodes are downloaded again even if they are in the cache database already.
Get the actors for SERIESNAME from thetvtb.com, which is returned as a hashref. If NOCACHE is non-zero, then the list of actors are downloaded again even if they are in the cache database already.
Get the actors for SERIESNAME from thetvtb.com, which is returned as an arrayref sorted by SortOrder. If NOCACHE is non-zero, then the list of actors are downloaded again even if they are in the cache database already.
Get the banners for SERIESNAME from thetvtb.com. Info about the available banners are returned in a hashref. The actual banners can be downloaded individually with getBanner (see below). If NOCACHE is non-zero, then the list of banners are downloaded again even if they are in the cache database already.
getBanner
if TYPE is specified (series, season, poster, or fanart) then only return banners of that type. if TYPE2 is specified then only return banners of that sub type. If TYPE is "series" then TYPE2 can be "text", "graphical", or "blank". If TYPE is "season" then TYPE2 can be "season", or "seasonwide" and VALUE specifies the season number. If TYPE is "fanart" then TYPE2 is the desired resolution of the image.
TYPE
TYPE2
Return a string for KEY in the hashref for SERIESNAME. If NOCACHE is non-zero, then the series is downloaded again even if it is in the cache database already.
Get the SERIESNAME banner from thetvdb.com and save it in the BannerPath directory. The cached banner is updated via getUpdates when appropriate. If a BUFFER is provided (a scalar reference), the banner (newly downloaded, or from the cache) is loaded into it. If NOCACHE is non-zero, then the banner is downloaded again even if it is in the BannerPath directory already. It will return the path of the banner relative to the BannerPath directory.
BannerPath
getUpdates
BUFFER
Get the SERIESNAME fan art from thetvdb.com and save it in the BannerPath directory. The cached fan art is updated via getUpdates when appropriate. If a BUFFER is provided (a scalar reference), the fan art (newly downloaded, or from the cache) is loaded into it. If NOCACHE is non-zero, then the fan art is downloaded again even if it is in the BannerPath directory already. It will return the path of the fan art relative to the BannerPath directory.
Get the SERIESNAME poster from thetvdb.com and save it in the BannerPath directory. The cached poster is updated via getUpdates when appropriate. If a BUFFER is provided (a scalar reference), the poster (newly downloaded, or from the cache) is loaded into it. If NOCACHE is non-zero, then the poster is downloaded again even if it is in the BannerPath directory already. It will return the path of the poster relative to the BannerPath directory.
Get the series overview from thetvdb.com and return it as a string. If NOCACHE is non-zero, then the banner is downloaded again even if it is in the cache database already.
Get the BANNER from thetvdb.com and save it in the BannerPath directory. The cached banner is updated via getUpdates when appropriate. If a BUFFER is provided (a scalar reference), the picture (newly downloaded, or from the cache) is loaded into it. If NOCACHE is non-zero, then the banner is downloaded again even if it is in the BannerPath directory already. It will return the path of the picture relative to the BannerPath directory. In this case it will just be the same as BANNER.
The minBannerTime configuration variable determines the maximum time a banner download failure will be cached. (see getConf()/setConf()).
minBannerTime
Return the number of the last season for SERIESNAME. If NOCACHE is non-zero, then any series info needed to calculate this is downloaded again even if it is in the cache database already.
Return a hashref of episodes in SEASON for SERIESNAME. If NOCACHE is non-zero, then any episodes needed for this season is downloaded again even if it is in the cache database already.
SEASON
The maxSeason configuration variable determines the maximum allowable season (see getConf()/setConf()).
maxSeason
Return an array of banner names for SEASON for SERIESNAME. These names can get used with getBanner() to actually download the banner file. If NOCACHE is non-zero, then any data needed for this is downloaded again even if it is in the cache database already.
getBanner()
Get a random banner for SEASON for SERIESNAME. The cached banner is updated via getUpdates when appropriate. If a BUFFER is provided (a scalar reference), the banner (newly downloaded, or from the cache) is loaded into it. If NOCACHE is non-zero, then the banner is downloaded again even if it is in the BannerPath directory already. It will return the path of the banner relative to the BannerPath directory.
Return an array of wide banner names for SEASON for SERIESNAME. These names can get used with getBanner() to actually download the banner file. If NOCACHE is non-zero, then any data needed for this is downloaded again even if it is in the BannerPath directory already.
Return the number episodes in SEASON for SERIESNAME. If NOCACHE is non-zero, then any series info needed to calculate this is downloaded again even if it is in the cache database already.
The maxEpisode configuration variable determines the maximum allowable episode (see getConf()/setConf()).
maxEpisode
Return a hashref for the EPISODE in SEASON for SERIESNAME. If NOCACHE is non-zero, then the episode is downloaded again even if it is in the cache database already.
EPISODE
The minEpisodeTime configuration variable determines the maximum time a episode lookup failure will be cached. (see getConf()/setConf()).
minEpisodeTime
Return a hashref for the absolute episode (ABSEPISODE) for SERIESNAME. If NOCACHE is non-zero, then the episode is downloaded again even if it is in the cache database already.
ABSEPISODE
Return a hashref for the EPISODE in SEASON for SERIESNAME in DVD order. If NOCACHE is non-zero, then the episode is downloaded again even if it is in the cache database already.
Return a hashref for the episode indicated by EPISODEID. If NOCACHE is non-zero, then the episode is downloaded again even if it is in the cache database already.
EPISODEID
Return a hashref for the episode in SERIESNAME on AIRDATE. AIRDATE can be specified as:
AIRDATE
2008-01-01 2008-1-1 January 1, 2008 1/1/2008
Currently this lookup is not cached. However, if NOCACHE is non-zero, then the SERIESNAME to seriesid lookup is downloaded again.
Return a string for KEY in the hashref for EPISODE in SEASON for SERIESNAME. If NOCACHE is non-zero, then the episode is downloaded again even if it is in the cache database already.
Get the episode banner for EPISODE in SEASON for SERIESNAME. The cached banner is updated via getUpdates when appropriate. If a BUFFER is provided, the picture (newly downloaded, or from the cache) is loaded into it. If NOCACHE is non-zero, then the banner is downloaded again even if it is in the BannerPath directory already. It will return the path of the picture relative to the BannerPath directory.
Return the episode name for EPISODE in SEASON for SERIESNAME. If NOCACHE is non-zero, then the episode is downloaded again even if it is in the cache database already.
Return the overview for EPISODE in SEASON for SERIESNAME. If NOCACHE is non-zero, then the episode is downloaded again even if it is in the cache database already.
Get the series ratings for USERID. If SERIESNAME is specified, the user/community ratings for the series and its episodes are returned in a hashref. If SERIESNAME is not specified, then all the series rated by the <USERID> will be returned in a hashref. These lookups are not cached.
USERID
Dump the cache database with Dumper to stdout.
use Data::Dumper; use TVDB::API; my $episode = $tvdb->getEpisode('Lost', 3, 5); print Dumper($episode); Produces: $episode = { 'lastupdated' => '1219734325', 'EpisodeName' => 'The Cost of Living', 'seasonid' => '16270', 'Overview' => 'A delirious Eko wrestles with past demons; some of the castaways go to the Pearl station to find a computerthey can use to locate Jack, Kate and Sawyer; Jack does not know who to trust when two of the Others are at odds with each other.', 'filename' => 'episodes/73739-308051.jpg', 'EpisodeNumber' => '5', 'Language' => 'en', 'Combined_season' => '3', 'FirstAired' => '2006-11-01', 'seriesid' => '73739', 'Director' => 'Jack Bender', 'SeasonNumber' => '3', 'Writer' => 'Monica Owusu-Breen, Alison Schapker', 'GuestStars' => '|Olalekan Obileye| Kolawole Obileye Junior| Alicia Young| Aisha Hinds| Lawrence Jones| Ariston Green| Michael Robinson| Jermaine|', 'Combined_episodenumber' => '5' };
Behan Webster <behanw@websterwood.com>
Copyright (c) 2008 Behan Webster. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install TVDB::API, copy and paste the appropriate command in to your terminal.
cpanm
cpanm TVDB::API
CPAN shell
perl -MCPAN -e shell install TVDB::API
For more information on module installation, please visit the detailed CPAN module installation guide.