NAME

WWW::RottenTomatoes - A Perl interface to the Rotten Tomatoes API

VERSION

Version 0.03

SYNPOSIS

    use WWW::RottenTomatoes;

    my $rt = WWW::RottenTomatoes->new(
        api_key      => 'your_api_key',
        pretty_print => 'true'
    );

    $rt->movies_search( query => 'The Goonies' );

DESCRIPTION

This module is intended to provide an interface between Perl and the Rotten Tomatoes JSON API. The Rotten Tomatoes API is a RESTful web service. In order to use this library you must provide an api key which requires registration. For more information please see Http://dev.rottentomatoes.com

CONSTRUCTOR

new()

Creates and returns a new WWW::RottenTomatoes object

    my $api= WWW::RottenTomatoes->new()
  • api_key => [your_api_key]

    The api_key parameter is required. You must provide a valid key.

  • pretty_print => [true]

    This parameter allows you to enable the pretty print function of the API. By default this parameter is set to false meaning you do not have to specify the parameter unless you intend to set it to true.

SUBROUTINES/METHODS

$obj->movies_search(...)

The movies search endpoint for plain text queries

    $api->movies_search( 
        query      => $search_query,
        page       => $page,
        page_limit => $page_limit 
    );

* query string, required: true

plain text search query

* page_limit integer, required: false, default: 30

the amount of movie search results to show per page

* page integer, required: false, default: 1

the selected page of movie search results

$obj->lists_directory

Displays the top level lists available in the API

* no parameters required

$obj->movie_lists_directory

Shows the movie lists we have available

* no parameters required

$obj->dvd_lists_directory

Shows the DVD lists we have available

* no parameters required

$obj->opening_movies(...)

Retrieves current opening movies

    $obj->opening_movies(
        limit   => 5,
        country => 'us'
    );

* limit integer, required: false, default: 16

limits number of movies returned

* country string, required: false, default: "us"

provides localized data for selected country (ISO 3166-1 alpha-2)

$obj->upcoming_movies(...)

Retrieves upcoming movies

    $obj->upcoming_movies(
        page_limit => 5,
        page       => 2,
        country    => 'uk'
    ); 

* page_limit integer, required: false, default: 16

the amount of upcoming movies to show per page

* page integer, required: false, default: 1

the selected page of upcoming movies

* country string, required: false, default: "us"

provides localized data for selected country (ISO 3166-1 alpha-2)

$obj->new_release_dvds(...)

Retrieves new release dvds

    $obj->new_release_dvds(
        page_limit => 10,
        page       => 3,
        country    => 'ca'
    );

* page_limit integer, required: false, default: 16

The amount of new release dvds to show per page

* page integer, required: false, default: 1

The selected page of new release dvds

* country string, required: false, default: "us"

provides localized data for selected country (ISO 3166-1 alpha-2)

$obj->movie_info(...)

Detailed information on a specific movie specified by Id. You can use the movies search endpoint or peruse the lists of movies/dvds to get the urls to movies.

     $obj->movie_info( movie_id => 770672122 ); 

* movie_id integer, required: true

The unique id (value) for a movie

$obj->movie_cast(...)

Pulls the complete movie cast for a movie

     $obj->movie_cast( movie_id => 770672122 );

* movie_id integer, required: true

The unique id (value) for a movie

$obj->movie_reviews(...)

Retrieves the reviews for a movie. Results are paginated if they go past the specified page limit

    $obj->movie_reviews(
        movie_id    => 770672122,
        review_type => 'dvd',
        page_limit  => 1,
        page        => 5,
        country     => 'us'
    );

* movie_id integer, required: true

The unique id (value) for a movie

* review_type string, required: false, default: top_critic

3 different review types are possible: "all", "top_critic" and "dvd". "top_critic" shows all the Rotten "top_critic" shows all the Rotten. "dvd" pulls the reviews given on the DVD of the movie. "all" as the name implies retrieves all reviews

* page_limit integer, required: false, default: 16

The amount of movie reviews to show per page

* page integer, required: false, default: 1

The selected page of movie reviews

* country string, required: false, default: "us"

provides localized data for selected country (ISO 3166-1 alpha-2)

$obj->movie_similar(...)

Shows similar movies for a movies

    $obj->movies_similar(
        movie_id => 770672122,
        limit    => 3
    );

* movie_id integer, required: true

The unique id (value) for a movie

$obj->in_theatre_movies(...)

Retrieves movies currently in theaters

    $obj->in_theatre_movies(
        page_limit  => 3,
        page        => 2,
        country     => 'mx'
    );

* page_limit integer, required: false, default: 16

The amount of in theatre movies to show per page

* page integer, required: false, default: 1

The selected page of in theatre movies

* country string, required: false, default: "us"

provides localized data for selected country (ISO 3166-1 alpha-2)

$obj->callback(...)

JSONP Support

    $obj->callback(
        callback_fn => method();
    );

* callback_fn

The API supports JSONP calls. Simply append a callback parameter with the name of your callback method at the end of the request.

DIAGNOSTICS

N/A at the current point in time

CONFIGURATION AND ENVIRONMENT

This package has only been tested in a 64bit Unix (OSX) environment however it does not make usage of any code or modules considered OS specific and no special configuration and or configuration files are needed.

INCOMPATIBILITIES

This package is intended to be compatible with Perl 5.008 and beyond.

BUGS AND LIMITATIONS

Current limitations exist in the amount of http requests that can be made against the API. The scope of this limitation exists outside of the code base.

DEPENDENCIES

REST::Client, URI::Escape

SEE ALSO

http://developer.rottentomatoes.com/docs

You may notice differences in the required parameters of this script and the documentation. The differences are typically stop gaps to prevent the API from empty results. A good example is the movie_search method. Without a text ( or a url encoded ) search term you will not return any results.

SUPPORT

The module is provided free of support however feel free to contact the author or current maintainer with questions, bug reports, and patches.

Considerations will be taken when making changes to the API. Any changes to its interface will go through at the least one deprecation cycle.

LICENSE AND COPYRIGHT

Copyright (c) 2011 Casey W. Vega.

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

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

Author

Casey Vega <cvega@cpan.org>