/ 
WWW-TheMovieDB-0.04
River stage zero No dependents
/ WWW::TheMovieDB

NAME

WWW::TheMovieDB - Complete Perl client to the TMDb API

SYNOPSIS

A full feature TMDb client.

DESCRIPTION

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

DOCUMENTATION

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

Sessions & Guest Sessions

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

  • Movies::rate

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'
});

OR

$api->session_id('000000000000000000000000000000000');

OR

$api->guest_session_id('000000000000000000000000000000000');

OR

$api->Movies::rate({
	'session_id' => '000000000000000000000000000000000',
	'id' => 550,
	'value' => '9.5'
});

OR

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

Methods

Basic Methods

api_key

Sets your API Key.

$api->api_key('000000000000000000000000000000000');

type

Sets the type of data you want to retrieve.

Default value: json

Available values: json

$api->type('000000000000000000000000000000000');

language

Sets the language based on ISO 639-1 Language Codes.

Default value: en

Available values: various

$api->language('en');

version

Sets the API version.

Default value: 3

Available values: 3

$api->version('3');

request_token

Sets the request token generated from Authentication.

$api->request_token('000000000000000000000000000000000');

session_id

Sets the session id generated from Authentication.

$api->session_id('000000000000000000000000000000000');

guest_session_id

Sets the guest session id generated from Authentication.

$api->guest_session_id('000000000000000000000000000000000');

user_id

Sets the user id.

$api->user_id('xxxxx');

Configuration

http://docs.themoviedb.apiary.io/#configuration

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

Authentication

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

Authentication::request_token

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

Authentication::session_new

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.

print $api->Authentication::session_new({
	'request_token' => '000000000000000000000000000000000'
});

Required Parameters

Authentication::guest_session_new

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.

print $api->Authentication::guest_session_new();

Account

http://docs.themoviedb.apiary.io/#account

Account::account

Get the basic information for an account. You will need to have a valid session id.

print $api->Account::account();

Required Parameters

  • session_id

Account::lists

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.

Required Parameters

  • session_id

  • user_id

    ID for the user.

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Account::favorite_movies

Get the list of favorite movies for an account.

print $api->Account::favorite_movies({
	'user_id' => '#####'
});

OR

$api->user_id('#####');
print $api->Account::favorite_movies();

Required Parameters

  • session_id

  • user_id

    ID of the user.

Optional Parameters

  • page

    Integer, default: 1

  • sort_by

    Only "created_at" is currently supported.

  • sort_order

    asc or desc, default: asc

  • language

    ISO 639-1 code, default: en

Account::favorite

Add or remove a movie to an accounts favorite list.

print $api->Account::favorite({
	'user_id'  => '#####',
	'movie_id' => 550,
	'favorite' => 'true'
});

Required Parameters

  • session_id

  • user_id

    ID of the user.

  • movie_id

    ID of the movie.

  • favorite

    true or false

Account::rated_movies

Get the list of rated movies (and associated rating) for an account.

print $api->Account::rated_movies({
	'user_id' => '#####'
});

OR

$api->user_id('#####');
print $api->Account::rated_movies();

Required Parameters

  • user_id

    ID of the user.

Account::movie_watchlist

Get the list of movies on an accounts watchlist.

print $api->Account::movie_watchlist({
	'user_id' => '#####'
});

Required Parameters

  • session_id

  • user_id

    ID of the user.

Account::modify_movie_watchlist

Add or remove a movie to an accounts watch list.

print $api->Account::modify_movie_watchlist({
	'user_id'         => '#####',
	'movie_id'        => 550,
	'movie_watchlist' => 'true'
});

Required Parameters

  • session_id

  • user_id

  • movie_id

  • movie_watchlist

    true or false, default: true

Movies

http://docs.themoviedb.apiary.io/#movies

Movies::info

Get the basic movie information for a specific movie id.

print $api->Movies::info({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Optional Parameters

  • language

    ISO 639-1 code, default: en

Movies::alternative_titles

Get the alternative titles for a specific movie id.

print $api->Movies::alternative_titles({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Optional Parameters

  • country

    ISO 3166-1 code.

Movies::casts

Get the cast information for a specific movie id.

print $api->Movies::casts({
	'movie_id' => 550
});

Movies::images

Get the images (posters and backdrops) for a specific movie id.

print $api->Movies::images({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Optional Parameters

  • language

    ISO 639-1 code, default: en

Movies::keywords

Get the plot keywords for a specific movie id.

print $api->Movies::keywords({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Movies::releases

Get the release date by country for a specific movie id.

print $api->Movies::releases({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Movies::trailers

Get the trailers for a specific movie id.

print $api->Movies::trailers({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Movies::translations

Get the translations for a specific movie id.

print $api->Movies::translations({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Movies::similar_movies

Get the similar movies for a specific movie id.

print $api->Movies::similar_movies({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Movies::reviews

Get the reviews for a particular movie id.

print $api->Movies::reviews({
	'movie_id' => 68734
});

Required Parameters

  • movie_id

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Movies::lists

Get the lists that the movie belongs to.

print $api->Movies::lists({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Movies::changes

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.

print $api->Movies::lists({
	'movie_id' => 550
});

Required Parameters

  • movie_id

Optional Parameters

  • start_date

    YYYY-MM-DD

  • end_date

    YYYY-MM-DD

Movies::latest

Get the latest movie id.

print $api->Movies::latest();

Movies::upcoming

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

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Movies::now_playing

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

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Movies::popular

Get the list of popular movies on The Movie Database. This list refreshes every day.

print $api->Movies::popular();

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Movies::top_rated

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

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Movies::account_states

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

Required Parameters

  • session_id

Movies::rate

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'
});

Required Parameters

  • session_id

  • guest_session_id

  • movie_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

Collections

http://docs.themoviedb.apiary.io/#collections

Collections::info

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

Optional Parameters

  • language

    ISO 639-1 code, default: en

Collections::images

Get all of the images for a particular collection by collection id.

print Collections::images();

Optional Parameters

  • language

    ISO 639-1 code, default: en

People

http://docs.themoviedb.apiary.io/#people

People::info

Get the general person information for a specific id.

print $api->People::info({
	'person_id' => 819
});

Required Parameters

  • person_id

People::credits

Get the credits for a specific person id.

print $api->People::credits({
	'person_id' => 819
});

Required Parameters

  • person_id

Optional Parameters

  • language

    ISO 639-1 code, default: en

People::images

Get the images for a specific person id.

print $api->People::images({
	'person_id' => 819
});

Required Parameters

  • person_id

People::changes

Get the changes for a specific person 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.

print $api->People::changes({
	'person_id' => 819
});

Required Parameters

  • person_id

Optional Parameters

  • start_date

    YYYY-MM-DD

  • end_date

    YYYY-MM-DD

People::popular

Get the list of popular people on The Movie Database. This list refreshes every day.

print $api->People::popular();

Optional Parameters

  • page

    Integer, default: 1

People::latest

Get the latest person id.

print $api->People::latest();

Lists

http://docs.themoviedb.apiary.io/#lists

Lists::info

Get a list by id.

print $api->Lists::info({
	'list_id' => '###'
});

Required Parameters

  • list_id

Lists::item_status

Check to see if a movie ID is already added to a list.

print $api->Lists::item_status({
	'list_id' => '###'
});

Required Parameters

  • list_id

  • movie_id

Lists::create

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.'
});

Required Parameters

  • session_id

  • name

    Name of the list.

  • description

    Description of the list

Optional Parameters

language

ISO 639-1 code, default: en

Lists::add_item

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'  => '###'
});

Required Parameters

  • session_id

  • list_id

  • movie_id

Lists::remove_item

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'  => '###'
});

Required Parameters

  • session_id

  • list_id

  • movie_id

Lists::delete

This method lets users delete a list that they created. A valid session id is required.

print $api->Lists::delete({
	'list_id' => '###'
});

Required Parameters

  • session_id

  • list_id

Companies

http://docs.themoviedb.apiary.io/#companies

Companies::info

This method is used to retrieve all of the basic information about a company.

print $api->Companies::info({
	'company_id'=>1632
});

Required Parameters

  • company_id

Companies::movies

Get the list of movies associated with a particular company.

print $api->Companies::movies({
	'company_id'=>1632
});

Required Parameters

  • company_id

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Genres

http://docs.themoviedb.apiary.io/#genres

Genres::list

Get the list of genres.

print $api->Genres::list();

Optional Parameters

  • language

    ISO 639-1 code, default: en

Genres::movies

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

Required Parameters

  • genre_id

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

  • 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

Keywords

http://docs.themoviedb.apiary.io/#keywords

Keywords::info

Get the basic information for a specific keyword id.

print $api->Keywords::info({
	'keyword_id'=>1541
});

Required Parameters

  • keyword_id

Keywords::movies

Get the list of movies for a particular keyword by id.

print $api->Keywords::movies({
	'keyword_id'=>1541
});

Required Parameters

  • keyword_id

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

Discover

http://docs.themoviedb.apiary.io/#discover

Discover::movie

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'
});

Optional Parameters

  • page

    Integer, default: 1

  • sort_by

    Available options are vote_average.desc, vote_average.asc, release_date.desc, release_date.asc, popularity.desc, popularity.asc

  • include_adult

    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::movie

Search for movies by title.

print $api->Search::movie({
	'query' => 'The%20Big'
});

Required Parameters

query CGI escaped string

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

  • include_adult

    Toggle the inclusion of adult titles. Expected value is: true or false

  • year

    Filter the results release dates to matches that include this value.

  • primary_release_year

    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::collection

Search for collections by name.

print $api->Search::collection({
	'query' => 'The%20Big'
);

Required Parameters

  • query

    CGI escaped string

Optional Parameters

  • page

    Integer, default: 1

  • language

    ISO 639-1 code, default: en

  • include_adult

    Toggle the inclusion of adult titles. Expected value is: true or false

  • year

    Filter the results release dates to matches that include this value.

  • primary_release_year

    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::person

Search for people by name.

print $api->Search::name({
	'query' => 'Edward%20Norton'
);

Required Parameters

  • query

    CGI escaped string

Optional Parameters

  • page

    Integer, default: 1

  • include_adult

    Toggle the inclusion of adult titles. Expected value is: true or false

  • 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::list

Search for lists by name and description.

$api->Search::list({
	'query' => 'Test'
});

Required Parameters

  • query

    CGI escaped string

Optional Parameters

  • page

    Integer, default: 1

  • include_adult

    Toggle the inclusion of adult lists.

Search::company

Search for companies by name.

print $api->Search::company({
	'query' => 'Lionsgate'
});

Required Parameters

  • query

    CGI escaped string

Optional Parameters

  • page

    Integer, default: 1

Search::keyword

Search for keywords by name.

print $api->Search::keyword({
	'query' => 'nihilism'
});

Required Parameters

  • query

    CGI escaped string

Optional Parameters

  • page

    Integer, default: 1

Reviews

http://docs.themoviedb.apiary.io/#reviews

Reviews::info

Get the full details of a review by ID.

print $api->Reviews::info({
	'review_id' => '51c2850e760ee359400fda6d'
});

Required Parameters

  • review_id

    ID of the review

Changes

http://docs.themoviedb.apiary.io/#changes

Changes::movie

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

Optional Parameters

  • page

    Integer, default: 1

  • start_date

    YYYY-MM-DD

  • end_date

    YYYY-MM-DD

Changes::person

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

Optional Parameters

  • page

    Integer, default: 1

  • start_date

    YYYY-MM-DD

  • end_date

    YYYY-MM-DD

Jobs

http://docs.themoviedb.apiary.io/#jobs

Jobs::list

Get a list of valid jobs.

print $api->Jobs::list();

REFERENCE

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

AUTHOR

Paul Jobson, <pjobson@gmail.com>

COPYRIGHT AND LICENSE

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.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 3260:

=over should be: '=over' or '=over positive_number'