An ActiveRecord-style API wrapper for
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib Version bump to 1.1.3 Jun 11, 2015



rottentomatoes is an ActiveRecord-style API wrapper for rottentomatoes is designed to make common tasks much easier than they would be if dealing directly with the URL based API.


gem install rottentomatoes


require 'rubygems'
require 'rottentomatoes'
include RottenTomatoes

# setup your API key
Rotten.api_key = "t478f8de5776c799de5a"

@movie = RottenMovie.find(:title => "Fight Club", :limit => 1)
# => <OpenStruct>

@movie = RottenMovie.find(:imdb => 137523)
# => <OpenStruct>

# => "Fight Club"

# => 81 

# => "An office employee and a soap salesman build a global organization to help vent male aggression."


RottenTomatoes provides two main object that you will use to query the API.


These objects provide access to movies and lists of movies respectively.

Each object provides a find() method which accepts a number of options:

RottenMovie.find(:id => 123, :title => "Fight Club", :limit => 10, :expand_results => true)

specifies an individual movie via it's RottenTomatoes id


specifies an individual movie via it's IMDb id


specifies a query string to look for in the movie titles


specifies the maximum number of results to be returned


The RottenTomatoes API by default returns only partial info for any API method that can return multiple results, or single movie lookups. When :expand_results is set to true rottentomatoes automatically makes extra API calls to fetch the full information for each item, such as the full cast and reviews. This can result in very slow requests though. If you need extra information for a search listing then set this to true. Defaults to 'false'. On average the overhead of the extra lookups takes 4x longer to return info.

RottenList.find(:type => "upcoming", :limit => 10, :expand_results => true)

specifies a list type to retrieve. Valid options are 'box_office', 'in_theaters', 'opening', 'upcoming', 'new_releases', 'top_rentals'.


see RottenMovie


see RottenMovie

Usage Examples

Find all movies whose titles match a given string:

@movies = RottenMovie.find(:title => 'Iron Man')

Find the movie most likely to be associated with a given title:

@movie = RottenMovie.find(:title => 'Sin City', :limit => 1)

Find a single movie by its RottenTomatoes ID:

@movie = RottenMovie.find(:id => 13153)

Find a single movie by its IMDb ID:

@movie = RottenMovie.find(:imdb => 137523)

Find a single movie and all associated information

@movie = RottenMovie.find(:title => 'Fight Club', :expand_results => true, :limit => 1)

Find movies that are playing in theatres

@movie = RottenList.find(:type => 'in_theaters')

Item information

To find out more about the information each object offers on retrieved items have a look at the RottenTomatoes API Docs. For the most accurate information about the information available have a look at the data directly through rottentomatoes by calling @item.raw_data.inspect

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history.

  • Send me a pull request.

Author & Credits


Nicholas Munson


Aaron Gough

Copyright © 2011 Nicholas Munson (, released under the MIT license