The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-TheMovieDB-Search.docupdate
++
/ WWW::TheMovieDB::Search

NAME

WWW::TheMovieDB::Search - Perl client to the TMDb API <http://api.themoviedb.org/2.1>

SYNOPSIS

A TMDb Search client.

DESCRIPTION

This client lets you retrieve data from the TMDb API; I currently have not implemented methods to write to the API, I don't really plan on it, unless someone really wants the feature.

It requires that you have a TMDb API key, which you can generate by getting an account at <http://api.themoviedb.org/2.1>.

NOTE

Most of this documentation is copied nearly verbatim from The Movie DB API documentation.

PUBLIC METHODS

new( $key )

Returns a new instance of this class. You are able to pass your API Key here or using the key method.

        my $api = new WWW::TheMovieDB::Search;
        my $api = new WWW::TheMovieDB::Search('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
lang( $lang )

Sets the search language type, default is en-US if none passed.

Primary language: 2-letter ISO-639 language code <http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>

        $api->lang('en');
        $api->lang('en');
        $api->lang('es');
        $api->lang('fr');
ver( $version )

Sets the version of the API to use, default is 2.1 if none passed.

        $api->ver('2.1');
key( $key )

Sets or changes the API key to use.

        $api->key('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
type( $type )

Sets the datatype to be returned, default is xml.

        $api->type('xml');
        $api->type('yaml');
        $api->type('json');
Movie_browse( %data )

<http://api.themoviedb.org/2.1/methods/Movie.browse>

The Movie_browse method is probably the most powerful single method on the entire TMDb API. While it might not be used by all apps, it is a great place to start if you're interested in building any kind of a top 10 list.

This method requires you pass two keys:

order_by

Three options: rating, release, title

order

Two options: asc, desc

You must also pass one or more of the following keys.

page

Results are paginated if you use the page & per_page parameters. You can quickly scan through multiple pages with these options. Value is expected to be an integer.

per_page

This value sets the number of results to display per page (or request). Without it, the default is 30 results. Value is expected to be an integer.

query

The search query parameter is used to search for some specific text from a title.

min_votes

Only return movies with a certain minimum number of votes. Expected value is an integer.

rating_min

If you'd only like to see movies with a certain minimum rating, use this. It is expected to be a float value and if used, rating_max is required.

rating_max

Used in conjunction with rating_min. Sets the upper limit of movies to return based on their rating. Expects this value to be a float.

genres

The genres parameter is to be passed the genres id(s) you want to search for. You can get these ids from the Genres_getList method. In the event you want to search for multiple genres, you have to pass the values as a comma separated value.

genres_selector

Two Options: and, or

Used when you search for more than 1 genre and useful to combine your genre searches.

release_min

Useful if you'd like to only search for movies from a particular date and on. If used, rating_max is required. The value is expected to be an epoch value.

release_max

Sets the upper date limit to search for. Like release_min this is expected to be an epoch value and if used, release_min is required.

year

If you'd only like to search for movies from a particular year, this if your option. Expects a single integer value.

certifications

Like genres, you can pass multiple values to this option. Comma separate them in this case. The values to be used here are the MPAA values like 'R' or 'PG-13'. When more than one value is passed, it is assumed to be an OR search.

companies

Useful if you'd like to find the movies from a particular studio. You can pass it more than one id which is expected to be comma separated. When more than one id is passed, it is assumed to be an OR search.

countries

If you'd like to limit your result set to movies from a particular country you can pass their 2 letter country code. You can pass more than one value and in this case make sure they are comma separated. When more than one id is passed, it is assumed to be an OR search.

        # Returns all movies rated 10.
        my $data = $api->Movie_browse(
                order_by                => 'rating',
                order                   => 'asc',
                rating_min              => '10'
        );
        
        # Returns all movies containing "inception"
        my $data = $api->Movie_browse(
                order_by                => 'rating',
                order                   => 'asc',
                query                   => 'inception'
        );
Movie_getImages( $movieid )

<http://api.themoviedb.org/2.1/methods/Movie.getImages>

The Movie_getImages method is used to retrieve all of the backdrops and posters for a particular movie. This is useful to scan for updates, or new images if that's all you're after. No point on calling Movie_getInfo if you're only interested in images.

This method expects either a TMDb Movie ID or IMDB Movie ID.

        $api->Movie_getImages('550');
        $api->Movie_getImages('tt0137523');
Movie_getInfo( $movieid )

<http://api.themoviedb.org/2.1/methods/Movie.getInfo>

The Movie_getInfo method is used to retrieve specific information about a movie. Things like overview, release date, cast data, genre's, YouTube trailer link, etc...

This method expects a TMDb Movie ID.

        $api->Movie_getInfo('550');
Movie_getLatest

<http://api.themoviedb.org/2.1/methods/Movie.getLatest>

The Movie_getLatest method is a simple method. It returns the ID of the last movie created in the db. This is useful if you are scanning the database and want to know which id to stop at.

        $api->Movie_getLatest();
Movie_getTranslations( $movieid )

<http://api.themoviedb.org/2.1/methods/Movie.getTranslations>

The Movie_getTranslations method will return the translations that a particular movie has. The languages returned can then be used with the Movie_search or Movie_getInfo methods. Remember though, just because the language was added to the movie it doesn't mean the data is complete.

This method expects a TMDb Movie ID.

        $api->Movie_getTranslations('550');
Movie_getVersion( $movieid )

<http://api.themoviedb.org/2.1/methods/Movie.getVersion>

The Movie_getVersion method is used to retrieve the last modified time along with the current version number of the called object(s). This is useful if you've already called the object sometime in the past and simply want to do a quick check for updates. This method supports calling anywhere between 1 and 50 items at a time.

This method expects a single TMDb Movie ID or set of IDs.

        $api->Movie_getVersion('585');
        $api->Movie_getVersion('585,155,11,550');
Movie_imdbLookup( $imdbid )

<http://api.themoviedb.org/2.1/methods/Movie.imdbLookup>

The Movie_imdbLookup method is the easiest and quickest way to search for a movie based on it's IMDb ID. You can use Movie.imdbLookup method to get the TMDb id of a movie if you already have the IMDB id.

This method expects an IMDB Movie ID.

        $api->Movie_imdbLookup('tt0137523');
Movie_search( $query )

<http://api.themoviedb.org/2.1/methods/Movie.search>

The Movie_search method is the easiest and quickest way to search for a movie. It is a mandatory method in order to get the movie id to pass to (as an example) the Movie_getInfo method.

This method

        $api->Movie_search('Transformers');
        $api->Movie_search('Transformers 2007');
Person_getInfo( $personid )

<http://api.themoviedb.org/2.1/methods/Person.getInfo>

The Person_getInfo method is used to retrieve the full filmography, known movies, images and things like birthplace for a specific person in the TMDb database.

This method expects a TMDb Person ID.

        $api->Person_getInfo('500');
Person_getLatest

<http://api.themoviedb.org/2.1/methods/Person.getLatest>

The Person_getLatest method is a simple method. It returns the ID of the last person created in the db. This is useful if you are scanning the database and want to know which id to stop at.

        $api->Person_getLatest();
Person_getVersion

<http://api.themoviedb.org/2.1/methods/Person.getVersion>

The Person_getVersion method is used to retrieve the last modified time along with the current version number of the called object(s). This is useful if you've already called the object sometime in the past and simply want to do a quick check for updates. This method supports calling anywhere between 1 and 50 items at a time.

This method expects a single TMDb Person ID or set of IDs.

        $api->Person_getVersion('287');
        $api->Person_getVersion('287,5064,819');
Person_search( $query )

<http://api.themoviedb.org/2.1/methods/Person.search>

The Person_search method is used to search for an actor, actress or production member.

This method expects a query.

        $api->Person_search('Brad Pitt');
        $api->Person_search('James Earl Jones');
Genres_getList

<http://api.themoviedb.org/2.1/methods/Genres.getList>

The Genres_getList method is used to retrieve a list of valid genres within TMDb. You can also request the translated values by passing the language option.

        $api->Genres_getList();

PRIVATE METHODS

buildURL( $type )

Builds a URL based on type passed and set values from class, expects one of the following: Movie.browse, Movie.getImages, Movie.getInfo, Movie.getLatest, Movie.getTranslations, Movie.getVersion, Movie.imdbLookup, Movie.search, Person.getInfo, Person.getLatest, Person.getInfo, Person.search, Genres.getList

AUTHOR

Paul Jobson, <pjobson@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Paul Jobson

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.