Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  IMDB::FILM (3)

.ds Aq ’


IMDB::Film - OO Perl interface to the movies database IMDB.



        use IMDB::Film;

        # Retrieve a movie information by its IMDB code
        my $imdbObj = new IMDB::Film(crit => 227445);


        # Retrieve a movie information by its title
        my $imdbObj = new IMDB::Film(crit => Troy);


        # 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;



IMDB::Film is an object-oriented interface to the IMDB. You can use that module to retrieve information about film: title, year, plot etc.


new() Object’s constructor. You should pass as parameter movie title or IMDB code.

        my $imdb = new IMDB::Film(crit => <some code>);


        my $imdb = new IMDB::Film(crit => <some title>);

        my $imdb = new IMDB::Film(crit => <HTML file>);

For more infomation about base methods refer to IMDB::BaseClass.

_init() Initialize object.


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 =>

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 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
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=’


        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();


 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:

        $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();


        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.




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 Cant 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: $@!";


Please, send me any found bugs by email: or create a bug report:


IMDB::Persons IMDB::BaseClass WWW::Yahoo::Movies IMDB::Movie HTML::TokeParser


Michael Stepanov AKA nite_man (


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.


Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 1522: Expected text after =item, not a bullet
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 IMDB::FILM (3) 2013-01-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.