WWW::TheMovieDB - Complete Perl client to the TMDb API
A full feature TMDb client.
This module is a complete rewrite of my original WWW::TheMovieDB::Search which attempts to allow access to all methods of the API provided by TheMovieDB.
This module requires an API key for TheMovieDB.org, see: REFERENCE
The 000000000000000000000000000000000 should be replaced with your individual API key, you can get an API key from TheMovieDB. Review the REFERENCE section for more information.
Basic initialization.
use WWW::TheMovieDB; my $api = new WWW::TheMovieDB({ 'key'=>'000000000000000000000000000000000' });
Slightly advanced initialization.
use WWW::TheMovieDB; my $api = new WWW::TheMovieDB({ 'key' => '000000000000000000000000000000000', 'language' => 'en', 'version' => '3', 'type' => 'json', 'uri' => 'http://api.themoviedb.org' });
You can also set the globals via methods.
use WWW::TheMovieDB; my $api = new WWW::TheMovieDB(); $api->api_key('000000000000000000000000000000000'); $api->language('en'); # default: en $api->version('3'); # default: 3 $api->type('json'); # default: json
Some of the methods in this module require either a session_id or a guest_session_id.
Session
Account::account
Account::lists
Account::favorite_movies
Account::favorite
Account::rated_movies
Account::movie_watchlist
Account::modify_movie_watchlist
Movies::account_states
Movies::rate
Lists::create
Lists::add_item
Lists::remove_item
Lists::delete
Guest Session
To use these methods you can pass the ID in as such, you should never use both session_id and guest_session_id at the same time.
my $api = new WWW::TheMovieDB({ 'key' => '000000000000000000000000000000000', 'session_id' => '000000000000000000000000000000000' });
OR
my $api = new WWW::TheMovieDB({ 'key' => '000000000000000000000000000000000', 'guest_session_id' => '000000000000000000000000000000000' });
$api->session_id('000000000000000000000000000000000');
$api->guest_session_id('000000000000000000000000000000000');
$api->Movies::rate({ 'session_id' => '000000000000000000000000000000000', 'id' => 550, 'value' => '9.5' });
$api->Movies::rate({ 'guest_session_id' => '000000000000000000000000000000000', 'id' => 550, 'value' => '9.5' });
If you pass the id in using the session_id or guest_session_id method you will not need to pass it into the method later on.
$api->session_id('000000000000000000000000000000000'); $api->Movies::rate({ 'id' => 550, 'value' => '9.5' });
To generate a standard session you will first need to use:
print Authentication::request_token();
This will generate a hash which the end-user must authenticate, this process is outlined in the official tmdb documentation.
https://www.themoviedb.org/documentation/api/sessions
After the end-user authenticates you may use that request_token to generate a session.
print $api->Authentication::session_new({ 'request_token' => '000000000000000000000000000000000' });
This should return:
{"success":true,"session_id":"000000000000000000000000000000000"}
Otherwise you can generate a guest session as such, but you will only be able to rate movies with it.
print $api->Authentication::guest_session_new();
Sets your API Key.
$api->api_key('000000000000000000000000000000000');
Sets the type of data you want to retrieve.
Default value: json
Available values: json
$api->type('json');
Sets the language based on ISO 639-1 Language Codes.
Default value: en
Available values: various
$api->language('en');
Sets the API version.
Default value: 3
Available values: 3
$api->version('3');
Sets the request token generated from Authentication.
$api->request_token('000000000000000000000000000000000');
Sets the session id generated from Authentication.
Sets the guest session id generated from Authentication.
Sets the user id.
$api->user_id('xxxxx');
http://docs.themoviedb.apiary.io/#configuration
Get the system wide configuration information. Some elements of the API require some knowledge of this configuration data. The purpose of this is to try and keep the actual API responses as light as possible. It is recommended you store this data within your application and check for updates every so often.
print $api->Configuration::configuration();
http://docs.themoviedb.apiary.io/#authentication
Instructions for using the request_token and session_id listed below are available here: https://www.themoviedb.org/documentation/api/sessions
This method is used to generate a valid request token for user based authentication. A request token is required in order to request a session id. This token must be authenticated by the user via: http://www.themoviedb.org/authenticate/generated_request_token
print $api->Authentication::request_token();
This method is used to generate a session id for user based authentication. A session id is required in order to use any of the write methods.
Required Parameters
request_token
The request token parameter is the token you generated for the user to approve. The token needs to be approved by the user before being used here. You can read more about this http://www.themoviedb.org/documentation/api/sessions.
This method is used to generate a guest session id.
A guest session can be used to rate movies without having a registered TMDb user account. You should only generate a single guest session per user (or device) as you will be able to attach the ratings to a TMDb user account in the future. There is also IP limits in place so you should always make sure it's the end user doing the guest session actions.
If a guest session is not used for the first time within 24 hours, it will be automatically discarded.
http://docs.themoviedb.apiary.io/#account
Get the basic information for an account. You will need to have a valid session id.
print $api->Account::account();
session_id
Get the lists that you have created and marked as a favorite.
print $api->Account::lists({ 'user_id' => '#####' });
Where id is your account id, which you can get from Account::account.
user_id
ID for the user.
Optional Parameters
page
Integer, default: 1
language
ISO 639-1 code, default: en
Get the list of favorite movies for an account.
print $api->Account::favorite_movies({ 'user_id' => '#####' });
$api->user_id('#####'); print $api->Account::favorite_movies();
ID of the user.
sort_by
Only "created_at" is currently supported.
sort_order
asc or desc, default: asc
Add or remove a movie to an accounts favorite list.
print $api->Account::favorite({ 'user_id' => '#####', 'movie_id' => 550, 'favorite' => 'true' });
movie_id
ID of the movie.
favorite
true or false
Get the list of rated movies (and associated rating) for an account.
print $api->Account::rated_movies({ 'user_id' => '#####' });
$api->user_id('#####'); print $api->Account::rated_movies();
Get the list of movies on an accounts watchlist.
print $api->Account::movie_watchlist({ 'user_id' => '#####' });
Add or remove a movie to an accounts watch list.
print $api->Account::modify_movie_watchlist({ 'user_id' => '#####', 'movie_id' => 550, 'movie_watchlist' => 'true' });
movie_watchlist
true or false, default: true
http://docs.themoviedb.apiary.io/#movies
Get the basic movie information for a specific movie id.
print $api->Movies::info({ 'movie_id' => 550 });
Get the alternative titles for a specific movie id.
print $api->Movies::alternative_titles({ 'movie_id' => 550 });
country
ISO 3166-1 code.
Get the cast information for a specific movie id.
print $api->Movies::casts({ 'movie_id' => 550 });
Get the images (posters and backdrops) for a specific movie id.
print $api->Movies::images({ 'movie_id' => 550 });
Get the plot keywords for a specific movie id.
print $api->Movies::keywords({ 'movie_id' => 550 });
Get the release date by country for a specific movie id.
print $api->Movies::releases({ 'movie_id' => 550 });
Get the trailers for a specific movie id.
print $api->Movies::trailers({ 'movie_id' => 550 });
Get the translations for a specific movie id.
print $api->Movies::translations({ 'movie_id' => 550 });
Get the similar movies for a specific movie id.
print $api->Movies::similar_movies({ 'movie_id' => 550 });
Get the reviews for a particular movie id.
print $api->Movies::reviews({ 'movie_id' => 68734 });
Get the lists that the movie belongs to.
print $api->Movies::lists({ 'movie_id' => 550 });
Get the changes for a specific movie id.
Changes are grouped by key, and ordered by date in descending order. By default, only the last 24 hours of changes are returned. The maximum number of days that can be returned in a single request is 14. The language is present on fields that are translatable.
start_date
YYYY-MM-DD
end_date
Get the latest movie id.
print $api->Movies::latest();
Get the list of upcoming movies. This list refreshes every day. The maximum number of items this list will include is 100.
print $api->Movies::upcoming();
Get the list of movies playing in theatres. This list refreshes every day. The maximum number of items this list will include is 100.
print $api->Movies::now_playing();
Get the list of popular movies on The Movie Database. This list refreshes every day.
print $api->Movies::popular();
Get the list of top rated movies. By default, this list will only include movies that have 10 or more votes. This list refreshes every day.
print $api->Movies::top_rated();
This method lets users get the status of whether or not the movie has been rated or added to their favourite or watch lists. A valid session id is required.
print $api->Movies::account_states();
This method lets users rate a movie. A valid session id or guest session id is required.
print $api->Movies::rate({ 'movie_id' => 550, 'value' => '9.5' });
guest_session_id
value
Available values: 0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10
http://docs.themoviedb.apiary.io/#collections
Get the basic collection information for a specific collection id. You can get the ID needed for this method by making a /movie/{id} request and paying attention to the belongs_to_collection hash.
Movie parts are not sorted in any particular order. If you would like to sort them yourself you can use the provided release_date.
print Collections::info();
Get all of the images for a particular collection by collection id.
print Collections::images();
http://docs.themoviedb.apiary.io/#people
Get the general person information for a specific id.
print $api->People::info({ 'person_id' => 819 });
person_id
Get the credits for a specific person id.
print $api->People::credits({ 'person_id' => 819 });
Get the images for a specific person id.
print $api->People::images({ 'person_id' => 819 });
Get the changes for a specific person id.
print $api->People::changes({ 'person_id' => 819 });
Get the list of popular people on The Movie Database. This list refreshes every day.
print $api->People::popular();
Get the latest person id.
print $api->People::latest();
http://docs.themoviedb.apiary.io/#lists
Get a list by id.
print $api->Lists::info({ 'list_id' => '###' });
list_id
Check to see if a movie ID is already added to a list.
print $api->Lists::item_status({ 'list_id' => '###' });
This method lets users create a new list. A valid session id is required.
print $api->Lists::create({ 'name' => 'My New List', 'description' => 'Blah blah blah.' });
name
Name of the list.
description
Description of the list
language ISO 639-1 code, default: en
This method lets users add new movies to a list that they created. A valid session id is required.
print $api->Lists::add_item({ 'movie_id' => 550, 'list_id' => '###' });
This method lets users delete movies from a list that they created. A valid session id is required.
print $api->Lists::remove_item({ 'movie_id' => 550, 'list_id' => '###' });
This method lets users delete a list that they created. A valid session id is required.
print $api->Lists::delete({ 'list_id' => '###' });
http://docs.themoviedb.apiary.io/#companies
This method is used to retrieve all of the basic information about a company.
print $api->Companies::info({ 'company_id'=>1632 });
company_id
Get the list of movies associated with a particular company.
print $api->Companies::movies({ 'company_id'=>1632 });
http://docs.themoviedb.apiary.io/#genres
Get the list of genres.
print $api->Genres::list();
Get the list of movies for a particular genre by id. By default, only movies with 10 or more votes are included.
print $api->Genres::movies({ 'genre_id'=>28 });
genre_id
include_all_movies
Toggle the inclusion of all movies and not just those with 10 or more ratings. true or false, default: false
include_adult
Include adult movies, true or false, default: false
http://docs.themoviedb.apiary.io/#keywords
Get the basic information for a specific keyword id.
print $api->Keywords::info({ 'keyword_id'=>1541 });
keyword_id
Get the list of movies for a particular keyword by id.
print $api->Keywords::movies({ 'keyword_id'=>1541 });
http://docs.themoviedb.apiary.io/#discover
Discover movies by different types of data like average rating, number of votes, genres and certifications.
print $api->Discover::movie(); print $api->Discover::movie({ 'sort_by' => 'popularity.desc', 'certification_country' => 'us' });
Available options are vote_average.desc, vote_average.asc, release_date.desc, release_date.asc, popularity.desc, popularity.asc
Toggle the inclusion of adult titles. Expected value is a boolean, true or false
year
Filter the results release dates to matches that include this value. Expected value is a year.
primary_release_year
Filter the results so that only the primary release date year has this value. Expected value is a year.
vote_count.gte
Only include movies that are equal to, or have a vote count higher than this value. Expected value is an integer.
vote_average.gte
Only include movies that are equal to, or have a higher average rating than this value. Expected value is a float.
with_genres
Only include movies with the specified genres. Expected value is an integer (the id of a genre). Multiple values can be specified. Comma separated indicates an 'AND' query, while a pipe (|) separated value indicates an 'OR'.
release_date.gte
The minimum release to include. Expected format is YYYY-MM-DD.
release_date.lte
The maximum release to include. Expected format is YYYY-MM-DD.
certification_country
Only include movies with certifications for a specific country. When this value is specified, 'certification.lte' is required. A ISO 3166-1 is expected.
certification.lte
Only include movies with this certification and lower. Expected value is a valid certification for the specificed 'certification_country'.
with_companies
Filter movies to include a specific company. Expected valu is an integer (the id of a company). They can be comma separated to indicate an 'AND' query.
http://docs.themoviedb.apiary.io/#search
Search for movies by title.
print $api->Search::movie({ 'query' => 'The%20Big' });
query CGI escaped string
Toggle the inclusion of adult titles. Expected value is: true or false
Filter the results release dates to matches that include this value.
Filter the results so that only the primary release dates have this value.
search_type
By default, the search type is 'phrase'. This is almost guaranteed the option you will want. It's a great all purpose search type and by far the most tuned for every day querying. For those wanting more of an "autocomplete" type search, set this option to 'ngram'.
Search for collections by name.
print $api->Search::collection({ 'query' => 'The%20Big' );
query
CGI escaped string
Search for people by name.
print $api->Search::name({ 'query' => 'Edward%20Norton' );
Search for lists by name and description.
$api->Search::list({ 'query' => 'Test' });
Toggle the inclusion of adult lists.
Search for companies by name.
print $api->Search::company({ 'query' => 'Lionsgate' });
Search for keywords by name.
print $api->Search::keyword({ 'query' => 'nihilism' });
http://docs.themoviedb.apiary.io/#reviews
Get the full details of a review by ID.
print $api->Reviews::info({ 'review_id' => '51c2850e760ee359400fda6d' });
review_id
ID of the review
http://docs.themoviedb.apiary.io/#changes
Get a list of movie ids that have been edited. By default we show the last 24 hours and only 100 items per page. The maximum number of days that can be returned in a single request is 14. You can then use the movie changes API to get the actual data that has been changed.
Please note that the change log system to support this was changed on October 5, 2012 and will only show movies that have been edited since.
print $api->Changes::movie();
Get a list of people ids that have been edited. By default we show the last 24 hours and only 100 items per page. The maximum number of days that can be returned in a single request is 14. You can then use the person changes API to get the actual data that has been changed.
Please note that the change log system to support this was changed on October 5, 2012 and will only show people that have been edited since.
print $api->Changes::person();
http://docs.themoviedb.apiary.io/#jobs
Get a list of valid jobs.
print $api->Jobs::list();
WWW::TheMovieDB requires the following modules:
HTTP::Request
LWP::UserAgent
URI::Escape
JSON
Full TheMovieDB API Documentation: http://docs.themoviedb.apiary.io/
API Key Sign-Up: https://www.themoviedb.org/account/signup
ISO 639-1 Language Codes: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
ISO 3166-1 Country Codes: https://en.wikipedia.org/wiki/List_of_ISO_3166-1_codes#Current_codes
Paul Jobson, <pjobson@gmail.com>
Copyright (C) 2013 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.12.4 or, at your option, any later version of Perl 5 you may have available.
To install WWW::TheMovieDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::TheMovieDB
CPAN shell
perl -MCPAN -e shell install WWW::TheMovieDB
For more information on module installation, please visit the detailed CPAN module installation guide.