NAME
====

TMDB - Perl wrapper for The MovieDB API

SYNOPSIS
========

    use TMDB;

    # Initialize
    my $tmdb = TMDB->new( apikey => 'xxxxxxxxxx' );

    # Search
    # =======

    # Search for a movie
    my @results = $tmdb->search->movie('Snatch');
    foreach my $result (@results) {
        printf( "%s:\t%s (%s)\n",
            $result->{id}, $result->{title},
            split( /-/, $result->{release_date}, 1 ) );
    }

    # Search for an actor
    my @results = $tmdb->search->person('Sean Connery');
    foreach my $result (@results) {
        printf( "%s:\t%s\n", $result->{id}, $result->{name} );
    }

    # Movie Data
    # ===========

    # Movie Object
    my $movie = $tmdb->movie( id => '107' );

    # Movie details
    my $movie_title     = $movie->title;
    my $movie_year      = $movie->year;
    my $movie_tagline   = $movie->tagline;
    my $movie_overview  = $movie->overview;
    my @movie_directors = $movie->director;
    my @movie_actors    = $movie->actors;

    printf( "%s (%s)\n%s", $movie_title, $movie_year,
        '=' x length($movie_title) );
    printf( "Tagline: %s\n",     $movie_tagline );
    printf( "Overview: %s\n",    $movie_overview );
    printf( "Directed by: %s\n", join( ',', @movie_directors ) );
    print("\nCast:\n");
    printf( "\t-%s\n", $_ ) for @movie_actors;

    # Person Data
    # ===========

    # Person Object
    my $person = $tmdb->person( id => '1331' );

    # Person Details
    my $person_name   = $person->name;
    my $person_bio    = $person->bio;
    my @person_movies = $person->starred_in;

    printf( "%s\n%s\n%s\n",
        $person_name, '=' x length($person_name), $person_bio );
    print("\nActed in:\n");
    printf( "\t-%s\n", $_ ) for @person_movies;

DESCRIPTION
===========

The MovieDB is a free and open movie database. This module provides a
Perl wrapper to The MovieDB API. In order to use this module, you must
first get an API key by signing up.

NOTE: TMDB-v0.04 and higher uses TheMoviDB API version /3. This brings
some significant differences both to the API and the interface this
module provides, along with updated dependencies for this distribution.
If you like to continue to use v2.1 API, you can continue to use
TMDB-0.03x.

INITIALIZATION
==============

-   new()

    Initialize
    ==========

    my $tmdb = TMDB->new( apikey => 'xxxxxxxxxx...', # API Key lang =>
    'en', # A valid ISO 639-1 (Aplha-2) language code client =>
    $http_tiny, # A valid HTTP::Tiny object json => $json_object, # A
    Valid JSON object );

The constructor accepts the following options:

    - apikey

    This is your API key

    - lang

    This must be a valid ISO 639-1 (Alpha-2) language code. Note that with `/3`,
    the API no longer falls back to an English default.

    [List of ISO 639-1 codes](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).

    - client

    You can provide your own [HTTP::Client](http://search.cpan.org/perldoc?HTTP::Client) object, otherwise a default one is
    used.

    - json

    You can provide your own [JSON](http://search.cpan.org/perldoc?JSON) implementation that can `decode` JSON. This
    will fall back to using [JSON::Any](http://search.cpan.org/perldoc?JSON::Any). However, [JSON::XS](http://search.cpan.org/perldoc?JSON::XS) is recommended.

CONFIGURATION
=============

    # Get Config
    my $config = $tmdb->config;
    print Dumper $config->config;   # Get all of it

    # Get the base URL
    my $base_url = $config->img_base_url();

    # Sizes (All are array-refs)
    my $poster_sizes   = $config->img_poster_sizes();
    my $backdrop_sizes = $config->img_backdrop_sizes();
    my $profile_sizes  = $config->img_profile_sizes();

This provides the configuration for the /3 API. See
http://help.themoviedb.org/kb/api/configuration for more details.

SEARCH
======

The following search methods are available.

-   movie()

    my $search = $tmdb->search(); my @results =
    $search->movie('Avatar'); # Search by Name my @results =
    $search->movie('Snatch (2000)'); # Include a Year for better results
-   person()

    my $search = $tmdb->search(); my @results = $search->person('Brad
    Pitt'); # Search by Name

Both search methods returns an array (or array-ref in a scalar context)
of hash-refs. See Movie Search or People Search for the list of
fields/keys returned.

MOVIE
=====

    # Get the movie object
    my $movie = $tmdb->movie( id => '107' );

    # Movie Data (as returned by the API)
    use Data::Dumper qw(Dumper);
    print Dumper $movie->info;
    print Dumper $movie->alternative_titles;
    print Dumper $movie->cast;
    print Dumper $movie->crew;
    print Dumper $movie->images;
    print Dumper $movie->keywords;
    print Dumper $movie->releases;
    print Dumper $movie->trailers;
    print Dumper $movie->translations;

    # Filtered Movie data
    print $movie->title;
    print $movie->year;
    print $movie->tagline;
    print $movie->overview;
    print $movie->description;         # Same as `overview`
    print $movie->genres;
    print $movie->imdb_id;
    print $movie->collection;          # Collection ID
    print $movie->actors;              # Names of Actors
    print $movie->director;            # Names of Directors
    print $movie->producer;            # Names of Producers
    print $movie->executive_producer;  # Names of Executive Producers
    print $movie->writer;              # Names of Writers/Screenplay

    # Images
    print $movie->poster;              # Main Poster
    print $movie->posters;             # list of posters
    print $movie->backdrop;            # Main backdrop
    print $movie->backdrops;           # List of backdrops
    print $movie->trailers_youtube;    # List of Youtube trailers URLs

    # Latest Movie on TMDB
    print Dumper $movie->latest;

PEOPLE
======

    # Get the person object
    my $person = $tmdb->person( id => '1331' );

    # Movie Data (as returned by the API)
    use Data::Dumper qw(Dumper);
    print Dumper $person->info;
    print Dumper $person->credits;
    print Dumper $person->images;

    # Filtered Person data
    print $person->name;
    print $person->aka;                 # Also Known As (list of names)
    print $person->bio;
    print $person->image;               # Main profile image
    print $person->starred_in;          # List of titles (as cast)
    print $person->directed;            # list of titles Directed
    print $person->produced;            # list of titles produced
    print $person->executive_produced;  # List of titles as an Executive Producer
    print $person->wrote;               # List of titles as a writer/screenplay

COLLECTION
==========

    # Get the collection object
    my $collection = $tmdb->collection(id => '2344');

    # Collection data (as returned by the API)
    use Data::Dumper;
    print Dumper $collection->info;


    # Filtered Collection Data
    print $collection->titles;  # List of titles in the collection
    print $collection->ids;     # List of movie IDs in the collection

DEPENDENCIES
============

-   Encode
-   HTTP::Tiny
-   JSON::Any
-   Locale::Codes
-   Object::Tiny
-   Params::Validate
-   URI::Encode

BUGS AND LIMITATIONS
====================

All data returned is UTF-8 encoded

Please report any bugs or feature requests to bug-tmdb@rt.cpan.org, or
through the web interface at
http://rt.cpan.org/Public/Dist/Display.html?Name=TMDB

AUTHOR
======

Mithun Ayachit mithun@cpan.org

LICENSE AND COPYRIGHT
=====================

Copyright (c) 2012, Mithun Ayachit. All rights reserved.

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
