rottentomatoes offers an easy-to-use Python wrapper to interact with the Rotten Tomatoes API. Before you try and use the API, make sure you sign up to get an API Key.


If you have pip installed, then run the following command:

pip install rottentomatoes

You can also run easy_install:

easy_install rottentomatoes

Or, if you want to help develop the package, just git clone the Github

git clone


Without saving your API key as a RT_KEY environment variable:

from rottentomatoes import RT

RT('my_api_key').search('some movie here')

With your API key saved:

from rottentomatoes import RT

RT().search('some movie here')

NOTE: Documentation from this point forward will assume you have saved your
Rotten Tomatoes Developer API Key as a RT_KEY environment variable:

$ RT_KEY='my_api_key'
$ echo $RT_KEY


Rotten Tomatoes movie search. Returns a list of dictionaries. Possible keyword arguments include: page and page_limit.

>>> rt = RT()
>>>'the lion king')
[{'movie': 'here'}, {'movie': 'here'}, ...]

>>>'fight club', page_limit=2)
[{'movie': 1}, {'movie': 2}]

>>>'disney', page=2)
[{'movie': 'from second page'}, {'movie': 'from second page'}, ...]


Displays the lists available in the Rotten Tomatoes API.

>>> rt = RT()
>>> rt.lists()
{'links': {'movies': 'http://link-to-movies',
           'dvds': 'http://link-to-dvds'}}

>>> rt.lists('dvds')
{'links': {'new_releases': 'http://link-to-new-releases'}}

>>> rt.lists(directory='dvds')
{'links': {'new_releases': 'http://link-to-new-releases'}}

>>> rt.lists('dvds', 'new_releases')
{'your data': 'is right here'}

>>> rt.lists(directory='dvds', sub='new_releases')
{'your data': 'is right here'}

>>> rt.lists('movies')
{'links': {'box_office': 'http://link-to-box-office-movies',
           'in_theaters': 'http://link-to-movies-in-theaters',
           'opening': 'http://link-to-opening-movies',
           'upcoming': 'http://link-to-upcoming-movies'}

>>> rt.lists('movies', 'box_office')
{'your data': 'is right here'}

>>> rt.lists('movies', 'box_office', page_limit=5)
{'only five': 'box office movies'}

>>> rt.lists('movies', 'opening')
{'your data': 'is right here'}


Return info for a movie given its id. Arguments for specific_info include cast and reviews.

>>> rt = RT()
>>> fight_club = '13153'
{'your data': 'is right here'}

>>>, 'cast')
{'cast info': 'is right here'}

>>>, 'reviews')
{'reviews': 'are right here'}


Short method to return just opened theatrical movies or newly released dvds. Returns a list of dictionaries.

>>> rt = RT()
[{'movie': 'here'}, {'movie': 'here'}, ...]

[{'dvd': 'here'}, {'dvd': 'here'}, ...]


Short method for returning specific movie lists. Possible sub arguments include: box_office, in_theaters, opening, and upcoming.

>>> rt = RT()
>>> rt.movies('in_theaters', page_limit=5)
{'top five': 'movies in theaters'}

>>> rt.movies('opening', page_limit=5)
{'top five': 'movies opening'}

>>> rt.movies('upcoming', page=2)
{'page 2': 'of upcoming movies'}

* `dvds` -- Short method for returning specific dvd lists. Currently, only one `sub` argument is possible: `new_releases`.
>>> RT().dvds(page_limit=5)
{'only 5': 'newly released dvds'}


Similar to Google's I'm Feeling Lucky button. Returns first instance of search term.

>>> RT().feeling_lucky('memento')
{'first result': 'for memento'}


In order to run the tests for, make sure you have the
mock library installed.

Also, all code complies with the PEP 8 Style Guide.