Paul Jobson > WWW-TheMovieDB-0.05 > WWW::TheMovieDB

Download:
WWW-TheMovieDB-0.05.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.05   Source  

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

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

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

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

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

Optional Parameters

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

Optional Parameters

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

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

Optional Parameters

Account::movie_watchlist

Get the list of movies on an accounts watchlist.

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

Required Parameters

Optional Parameters

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

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

Optional Parameters

Movies::alternative_titles

Get the alternative titles for a specific movie id.

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

Required Parameters

Optional Parameters

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

Optional Parameters

Movies::keywords

Get the plot keywords for a specific movie id.

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

Required Parameters

Movies::releases

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

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

Required Parameters

Movies::trailers

Get the trailers for a specific movie id.

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

Required Parameters

Movies::translations

Get the translations for a specific movie id.

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

Required Parameters

Movies::similar_movies

Get the similar movies for a specific movie id.

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

Required Parameters

Optional Parameters

Movies::reviews

Get the reviews for a particular movie id.

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

Required Parameters

Optional Parameters

Movies::lists

Get the lists that the movie belongs to.

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

Required Parameters

Optional Parameters

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

Optional Parameters

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

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

Movies::popular

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

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

Optional Parameters

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

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

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

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

Collections::images

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

        print Collections::images();

Optional Parameters

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

People::credits

Get the credits for a specific person id.

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

Required Parameters

Optional Parameters

People::images

Get the images for a specific person id.

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

Required Parameters

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

Optional Parameters

People::popular

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

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

Optional Parameters

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

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

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

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

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

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

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

Companies::movies

Get the list of movies associated with a particular company.

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

Required Parameters

Optional Parameters

Genres

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

Genres::list

Get the list of genres.

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

Optional Parameters

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

Optional Parameters

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

Keywords::movies

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

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

Required Parameters

Optional Parameters

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

Search

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

Search::collection

Search for collections by name.

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

Required Parameters

Optional Parameters

Search::person

Search for people by name.

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

Required Parameters

Optional Parameters

Search::list

Search for lists by name and description.

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

Required Parameters

Optional Parameters

Search::company

Search for companies by name.

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

Required Parameters

Optional Parameters

Search::keyword

Search for keywords by name.

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

Required Parameters

Optional Parameters

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

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

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

Jobs

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

Jobs::list

Get a list of valid jobs.

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

PREREQUISITES ^

WWW::TheMovieDB requires the following modules:

HTTP::Request

LWP::UserAgent

URI::Escape

JSON

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.

syntax highlighting: