File Coverage

blib/lib/WWW/TMDB/API.pm

Criterion	Covered	Total	%
statement	33	82	40.2
branch	0	16	0.0
condition	0	3	0.0
subroutine	11	21	52.3
pod	2	10	20.0
total	46	132	34.8

package WWW::TMDB::API;

use 5.006;
use strict;
use warnings;
use Carp;

our $VERSION = '0.04';
use utf8;
use LWP::UserAgent;
use HTTP::Request;
use JSON;
use URI;

our @namespaces = qw( Person Movie );
for (@namespaces) {
    my $package = __PACKAGE__ . "::$_";
    my $name    = "\L$_";
    eval qq(
    use $package;
    sub $name {
      my \$self = shift;
      if ( \$self->{'_$name'} ) {
        return \$self->{'_$name'};
      }else{
        \$self->{'_$name'} = $package->new( api => \$self );
      }
    };

    package $package;
    sub api {
      return shift->{api};
    };

    sub new {
      my ( \$class, \%params ) = \@_;
      my \$self = bless \\\%params, \$class;
      \$self->{api} = \$params{api};
      return \$self;
    };

    1;
  );
    croak "Cannot create namespace $name: $@\n" if $@;
}

sub send_api {
    my ( $self, $command, $params_spec, $params ) = @_;

    $self->check_parameters( $params_spec, $params );
    my $url = $self->url( $command, $params );
    my $request = HTTP::Request->new( GET => $url );
    $request->header( 'Accept' => 'application/json' );
    my $json_response = $self->{ua}->request($request);
    if ( $json_response->is_success ) {
        return decode_json $json_response->content();
    }
    else {
        croak
            sprintf( "%s returned by %s", $json_response->status_line, $url );
    }
}

# Checks items that will be sent to the API($input)
# $params - an array that identifies valid parameters
#     example :
#     {'ID' => 1 }, 1- field is required, 0- field is optional
sub check_parameters {
    my $self = shift;
    my ( $params, $input ) = @_;

    foreach my $k ( keys(%$params) ) {
        croak "Required parameter $k missing."
            if ( $params->{$k} == 1 and !defined $input->{$k} );
    }
    foreach my $k ( keys(%$input) ) {
        croak "Unknown parameter - $k." if ( !defined $params->{$k} );
    }
}

sub url {
    my $self = shift;
    my ( $command, $params ) = @_;
    my $url = new URI( $self->{url} );
    $url->path_segments( $self->{ver}, @$command );
    $params->{api_key} = $self->{api_key};
    $url->query_form($params);
    return $url->as_string();
}

sub new {
    my $class = shift;
    my (%params) = @_;

    croak "Required parameter api_key not provided." unless $params{api_key};
    if ( !defined $params{ua} ) {
        $params{ua} =
            LWP::UserAgent->new( 'agent' => "Perl-WWW-TMDB-API/$VERSION", );
    }
    else {
        croak "LWP::UserAgent expected."
            unless $params{ua}->isa('LWP::UserAgent');
    }

    my $self = {
        api_key => $params{api_key},
        ua      => $params{ua},
        ver     => '3',
        url     => 'http://api.themoviedb.org',
    };

    bless $self, $class;
    return $self;
}

=head1 NAME

WWW::TMDB::API - TMDb API (http://api.themoviedb.org) client

=head1 VERSION

Version 0.04

=head1 SYNOPSIS

        use WWW::TMDB::API;

        # The constructor has 2 parameters - the api_key and the optional LWP::UserAgent object, ua.
        my $tmdb_client = WWW::TMDB::API->new( 'api_key' => 'your tmdb api key' );

        #  Retrieve information about the person with ID == 287
        $tmdb_client->person->info( ID => 287 );

        # Searches the themoviedb.org database for an actor, actress or production member with name 'Brad+Pitt'
        $tmdb_client->person->search( query => 'Brad+Pitt' );

        # Searches the themoviedb.org database for an actor, actress or production member with name 'Brad'
        $tmdb_client->person->search( query => 'Brad' );

        #  Determines the last movie created in the themoviedb.org database.
        $tmdb_client->movie->latest();


=head1 DESCRIPTION

This module implements version 3 of the TMDb API. See L for the documentation.
The module uses the same parameter names used by the API.
The method names have been slightly changed. Here's the mapping of the method names used by this this module and the corresponding method names in the TMDb API:

                                      TMDB API                           WWW::TMDB::API
                                      ----------------------             -------------------
    Search Movies                     search/movie	                 movie->search()
    Search People                     search/person                      person->search()
    Movie Info                        movie/[TMDb ID]                    movie->info()
    Movie Alternative Titles          movie/[TMDb ID]/alternative_titles movie->alternative_titles()
    Movie Casts                       movie/[TMDb ID]/casts              movie->casts()
    Movie Images                      movie/[TMDb ID]/images             movie->images()
    Movie Keywords                    movie/[TMDb ID]/keywords           movie->keywords()
    Movie Release Info                movie/[TMDb ID]/releases           movie->releases()
    Movie Trailers                    movie/[TMDb ID]/trailers           movie->trailers()
    Movie Translations                movie/[TMDb ID]/translations       movie->translations()
    Person Info                       person/[TMDb ID]/info              person->info()
    Person Credits                    person/[TMDb ID]/credits           person->credits()
    Person Images                     person/[TMDb ID]/images            person->images()
    Latest Movie                      latest/movie                       movie->latest()


The API requires an API key which can be generated from http://api.themoviedb.org.
This module converts the API output to Perl data structure using the module JSON.
This module does not support update the method, Movie Add Rating.

=head1 SUBROUTINES/METHODS

=head2 new( %params )

Returns a new instance of the B class.

=over 4

=item * B

Required. This is the TMDb API key. Go to the L to signup and generate an API key.

=item * B

Optional. The LWP::UserAgent used to communicate with the TMDb server.


        my $tmdb_client = WWW::TMDB::API->new( 'api_key' => 'your tmdb api key' );

        require LWP::UserAgent;
        $ua = LWP::UserAgent->new(
                'agent'        => "Perl-WWW-TMDB-API",
        );

        my $tmdb_client =
                WWW::TMDB::API->new( 'api_key' => 'your tmdb api key', 'ua' => $ua );


=back

=head2  movie->search( %params )

Searches for movies.

=over 4

=item * B

Required. This is the search text. The query can include the year the movie was released (e.g. B) to narrow the search results.

=item * B

Optional. Use this parameter to iterate through the search results. Search results that exceed 20 items are paginated.

=item * B

Optional. This limits the result to items tagged with the specified language. The expected value is a ISO 639-1 code.

=item * B

Optional. [true/false, defaults to false if unspecified]. Set this to true to include adult items in the search results.

=back
         $result = $api->movie->search( 'query' => 'Cool Hand' );


=head2  person->search( %params )

Searches for actors, actresses, or production members.

=over 4

=item * B

Required. This is the search text.


=item * B

Optional. Use this parameter to iterate through the search results. Search results that exceed 20 items are paginated.

=back

        $result = $api->person->search( 'query' => 'Newman' );


=head2  movie->info( %params )

Retrieves basic information about a movie.
Building image urls from the file_paths returned by this method is discussed in the document L.

=over 4

=item * B

Required. The TMDb ID of the movie.

=item * B

Optional. This limits the result to items tagged with the specified language. The expected value is a ISO 639-1 code.

=back

        $result = $api->movie->info( ID => 903 );


=head2 movie->alternative_titles( %params )

Retrieves a movie's alternative titles.

=over 4

=item * B

Required. The TMDb ID of the movie.

=item * B

Optional. This limits the result to items tagged with the specified country. The expected value is a ISO 3166-1 code.

=back

        $result = $api->movie->alternative_titles( ID => 903 );
        $result = $api->movie->alternative_titles( ID => 903, 'language' => 'fr' );


=head2 movie->casts( %params )

Retrieves a movie's cast information.

=over 4

=item * B

Required. The TMDb ID of the movie.

=back

        $result = $api->movie->casts( ID => 903 );


=head2 movie->images( %params )

Retrieves all of the images for a particular movie.
Building image urls from the file_paths returned by this method is discussed in the document:
L

=over 4

=item * B

Required. The TMDb ID of the movie.

=item * B

Optional. This limits the result to items tagged with the specified language. The expected value is a ISO 639-1 code.

=back

        $result = $api->movie->images( ID => 903 );
        $result = $api->movie->images( ID => 903, 'language' => 'en' );


=head2 movie->keywords( %params )

Retrieves the keywords for a movie.

=over 4

=item * B

Required. The TMDb ID of the movie.

=back

        $result = $api->movie->keywords( ID => 903 );

=head2 movie->releases( %params )

Retrieves release and certification data for a specific movie.

=over 4

=item * B

Required. The TMDb ID of the movie.

=back

        $result = $api->movie->releases( ID => 903 );


=head2 movie->trailers( %params )

Retrieves the trailers for a movie.

=over 4

=item * B

Required. The TMDb ID of the movie.

=item * B

Optional. This limits the result to items tagged with the specified language. The expected value is a ISO 639-1 code.

=back

        $result = $api->movie->trailers( ID => 903 );


=head2 movie->translations( %params )

Retrieves the list of translations for a movie.

=over 4

=item * B

Required. The TMDb ID of the movie.

=back

        $result = $api->movie->translations( ID => 903 );


=head2  person->info( %params )

Retrieves basic information about a person.
Building image urls from the file_paths returned by this method is discussed in the document:
L

=over 4

=item * B

Required. The TMDb ID of the person.

=back

         $result = $api->person->info( ID => 3636 );

=head2  person->credits( %params )

Retrieves the movies that have cast or crew credits for  a person.

=over 4

=item * B

Required. The TMDb ID of the person.

=item * B

Optional. This limits the result to items tagged with the specified language. The expected value is a ISO 639-1 code.

=back

         $result = $api->person->credits( ID => 3636 );


=head2  person->images( %params )

Retrieves all the profile images of the person.
Building image urls from the file_paths returned by this method is discussed in the document:
L]

=over 4

=item * B

Required. The TMDb ID of the person.

=back

         $result = $api->person->images( ID => 3636 );


=head2  movie->latest( )

Returns the newest movie created in the themoviedb.org database.


=head1 AUTHOR

Maria Celina Baratang, C<<  >>

=head1 BUGS

Please report any bugs or feature requests to C, or through
the web interface at L.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WWW::TMDB::API


You can also look for information at:


=over 4

=item * TMDb The open movie database

L

=item * themoviedb.org API Documentation

L
L

=item * RT: CPAN's request tracker (report bugs here)

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=back


=head1 ACKNOWLEDGEMENTS

=head1 LICENSE AND COPYRIGHT

Copyright 2012 Maria Celina Baratang.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.


=cut

1;    # End of WWW::TMDB::API