Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Rotten Tomatoes API for Python
Branch: master
Failed to load latest commit information.
rottentomatoes Update documentation Remove untrue documentation
UNLICENSE Added UNLICENSE file Bump version to 2.1 Update version and tests

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 repository:

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.


Author: Zach Williams

All code released under the Unlicense (a.k.a. Public Domain).

Something went wrong with that request. Please try again.