Casey Vega > WWW-RottenTomatoes > WWW::RottenTomatoes

Download:
WWW-RottenTomatoes-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

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

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>

syntax highlighting: