Provided by: libimdb-film-perl_0.53-1_all 
NAME
IMDB::Film - OO Perl interface to the movies database IMDB.
SYNOPSIS
use IMDB::Film;
#
# Retrieve a movie information by its IMDB code
#
my $imdbObj = new IMDB::Film(crit => 227445);
or
#
# Retrieve a movie information by its title
#
my $imdbObj = new IMDB::Film(crit => 'Troy');
or
#
# Parse already stored HTML page from IMDB
#
my $imdbObj = new IMDB::Film(crit => 'troy.html');
if($imdbObj->status) {
print "Title: ".$imdbObj->title()."\n";
print "Year: ".$imdbObj->year()."\n";
print "Plot Symmary: ".$imdbObj->plot()."\n";
} else {
print "Something wrong: ".$imdbObj->error;
}
DESCRIPTION
Overview
IMDB::Film is an object-oriented interface to the IMDB. You can use that module to
retrieve information about film: title, year, plot etc.
Constructor
new()
Object's constructor. You should pass as parameter movie title or IMDB code.
my $imdb = new IMDB::Film(crit => <some code>);
or
my $imdb = new IMDB::Film(crit => <some title>);
or my $imdb = new IMDB::Film(crit => <HTML file>);
For more infomation about base methods refer to IMDB::BaseClass.
_init()
Initialize object.
Options
year
Define a movie's year. It's useful to use it to get the proper movie by its title:
my $imdbObj = new IMDB::Film(crit => 'Jack', year => 2003);
print "Got #" . $imdbObj->code . " " . $imdbObj->title . "\n"; #0379836
proxy
defines proxy server name and port:
proxy => 'http://proxy.myhost.com:80'
By default object tries to get proxy from environment
debug
switches on debug mode to display useful debug messages. Can be 0 or 1 (0 by default)
cache
indicates use cache or not to store retrieved page content. Can be 0 or 1 (0 by
default)
cache_root
specifies a directory to store cache data. By default it use /tmp/FileCache for *NIX
OS
cache_exp
specifies an expiration time for cache. By default, it's 1 hour
clear_cache
indicates clear cached data before get request to IMDB.com or not
timeout
specifies a timeout for HTTP connection in seconds (10 sec by default)
user_agent
specifies an user agent for request ('Mozilla/5.0' by default)
full_plot_url
specifies a full plot url for specified movie
host
specifies a host name for IMDB site. By default it's www.imdb.com
query
specifies a query string to get specified movie by its ID. By defualt it's 'title/tt'
search
specifies query string to make a search movie by its title. By default it's
'find?tt=on;mx=20;q='
Example:
my $imdb = new IMDB::Film( crit => 'Troy',
user_agent => 'Opera/8.x',
timeout => 2,
debug => 1,
cache => 1,
cache_root => '/tmp/imdb_cache',
cache_exp => '1 d',
);
It'll create an object with critery 'Troy', user agent 'Opera', timeout 2 seconds,
debug mode on, using cache with directory '/tmp/imdb_cache' and expiration time in 1
day.
Object Private Methods
_search_film()
Implemets functionality to search film by name.
Object Public Methods
status()
Indicates a status of IMDB object:
0 - empty object; 1 - loaded from file; 2 - loaded from internet request; 3 - loaded
from cache.
status_descr()
Return a description for IMDB object status. Can be 'Empty', 'Filed', 'Fresh' and
'Cached':
if($film->status) {
print "This is a " . $film->status_descr . " object!";
} else {
die "Cannot retrieve IMDB object!";
}
title()
Retrieve film title from film page. If was got search page instead of film page this
method calls method _search_film to get list matched films and continue to process
first one:
my $title = $film->title();
kind()
Get kind of movie:
my $kind = $film->kind();
Possible values are: 'movie', 'tv series', 'tv mini series', 'video game', 'video movie', 'tv movie', 'episode'.
year()
Get film year:
my $year = $film->year();
connections()
Retrieve connections for the movie as an arrays of hashes with folloeing structure
{
follows => [ { id => <id>, title => <name>, year => <year>, ..., } ],
followed_by => [ { id => <id>, title => <name>, year => <year>, ..., } ],
references => [ { id => <id>, title => <name>, year => <year>, ..., } ],
referenced_in => [ { id => <id>, title => <name>, year => <year>, ..., } ],
featured_in => [ { id => <id>, title => <name>, year => <year>, ..., } ],
spoofed_by => [ { id => <id>, title => <name>, year => <year>, ..., } ],
}
my %connections = %{ $film->connections() };
full_companies()
Retrieve companies for the movie as an array where each item has following stucture:
{
production => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ],
distributors => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ],
special_effects => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ],
other => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ],
}
my %full_companies = %{ $film->full_companies() };
company()
Returns a list of companies given for a specified movie:
my $company = $film->company();
or
my @companies = $film->company();
episodes()
Retrieve episodes info list each element of which is hash reference for tv series - {
id => <ID>, title => <Title>, season => <Season>, episode => <Episode>, date =>
<Date>, plot => <Plot> }:
my @episodes = @{ $film->episodes() };
episodeof()
Retrieve parent tv series list each element of which is hash reference for episode - {
id => <ID>, title => <Title>, year => <Year> }:
my @tvseries = @{ $film->episodeof() };
cover()
Retrieve url of film cover:
my $cover = $film->cover();
recommendation_movies()
Return a list of recommended movies for specified one as a hash where each key is a
movie ID in IMDB and value - movie's title:
$recommendation_movies = $film->recommendation_movies();
For example, the list of recommended movies for Troy will be similar to that:
__DATA__
$VAR1 = {
'0416449' => '300',
'0167260' => 'The Lord of the Rings: The Return of the King',
'0442933' => 'Beowulf',
'0320661' => 'Kingdom of Heaven',
'0172495' => 'Gladiator'
};
directors()
Retrieve film directors list each element of which is hash reference - { id => <ID>,
name => <Name> }:
my @directors = @{ $film->directors() };
writers()
Retrieve film writers list each element of which is hash reference - { id => <ID>,
name => <Name> }:
my @writers = @{ $film->writers() };
<I>Note: this method returns Writing credits from movie main page. It maybe not
contain a full list!</I>
genres()
Retrieve film genres list:
my @genres = @{ $film->genres() };
tagline()
Retrieve film tagline:
my $tagline = $film->tagline();
plot()
Returns a movie plot:
my $plot = $film->plot;
storyline()
Retrieve film plot summary:
my $storyline = $film->storyline();
rating()
In scalar context returns film user rating, in array context returns film rating,
number of votes and info about place in TOP 250 or some other TOP and avards:
my $rating = $film->rating();
or
my($rating, $vnum, $avards) = $film->rating();
print "RATING: $rating ($vnum votes)";
Note, that $avards is array reference where the first elemen is a TOP info if so, and
the next element is other avards - Oscar, nominations and etc
cast()
Retrieve film cast list each element of which is hash reference - { id => <ID>, name
=> <Full Name>, role => <Role> }:
my @cast = @{ $film->cast() };
<I> Note: this method retrieves a cast list first billed only! </I>
duration()
In the scalar context it retrieves a film duration in minutes (the first record):
my $duration = $film->duration();
In array context it retrieves all movie's durations:
my @durations = $film->duration();
country()
Retrieve film produced countries list:
my $countries = $film->country();
language()
Retrieve film languages list:
my $languages = $film->language();
also_known_as()
Retrieve AKA information as array, each element of which is string:
my $aka = $film->also_known_as();
print map { "$_\n" } @$aka;
trivia()
Retrieve a movie trivia:
my $trivia = $film->trivia();
goofs()
Retrieve a movie goofs:
my $goofs = $film->goofs();
awards()
Retrieve a general information about movie awards like 1 win & 1 nomination:
my $awards = $film->awards();
mpaa_info()
Return a MPAA for the specified move:
my mpaa = $film->mpaa_info();
aspect_ratio()
Returns an aspect ratio of specified movie:
my $aspect_ratio = $film->aspect_ratio();
summary()
Retrieve film user summary:
my $descr = $film->summary();
certifications()
Retrieve list of film certifications each element of which is hash reference - {
country => certificate }:
my @cert = $film->certifications();
full_plot
Return full movie plot.
my $full_plot = $film->full_plot();
official_sites()
Returns a list of official sites of specified movie as array reference which contains
hashes with site information - URL => Site Title:
my $sites = $film->official_sites();
for(@$sites) {
print "Site name - $_->{title}; url - $_->{url}\n";
}
release_dates()
Returns a list of release dates of specified movie as array reference:
my $sites = $film->release_dates();
for(@$sites) {
print "Country - $_->{country}; release date - $_->{date}; info - $_->{info}\n";
}
Option info contains additional information about release - DVD premiere, re-release,
restored version etc
Retrieve a list of plot keywords as an array reference:
my $plot_keywords = $film->plot_keywords();
for my $keyword (@$plot_keywords) {
print "keyword: $keyword\n";
}
Class Variables
%FIELDS
Contains list all object's properties. See description of pragma "fields".
@FILM_CERT
Matches USA film certification notation and age.
EXPORTS
Nothing
HOWTO CACTH EXCEPTIONS
If it's needed to get information from IMDB for a list of movies in some case it can be
returned critical error:
[CRITICAL] Cannot retrieve page: 500 Can't read entity body ...
To catch an exception can be used eval:
for my $search_crit ("search_crit1", "search_crit2", ..., "search_critN") {
my $ret;
eval {
$ret = new IMDB::Film(crit => "$search_crit") || print "UNKNOWN ERROR\n";
};
if($@) {
# Opsssss! We got an exception!
print "EXCEPTION: $@!";
next;
}
}
BUGS
Please, send me any found bugs by email: stepanov.michael@gmail.com or create a bug
report: http://rt.cpan.org/NoAuth/Bugs.html?Dist=IMDB-Film
SEE ALSO
IMDB::Persons IMDB::BaseClass WWW::Yahoo::Movies IMDB::Movie HTML::TokeParser
http://videoguide.sf.net
AUTHOR
Michael Stepanov AKA nite_man (stepanov.michael@gmail.com)
COPYRIGHT
Copyright (c) 2004 - 2007, Michael Stepanov. This module is free software. It may be
used, redistributed and/or modified under the same terms as Perl itself.