Skip to main content

A Python wrapper for the Rotten Tomatoes API v1.0

Project description

A wrapper for the Rotten Tomatoes API

rtsimple is a wrapper, written in Python, for the Rotten Tomatoes (RT) API. By calling the methods available in rtsimple you can simplify your code and easily access a vast amount of movie data, including detailed movie information, lists of new released movies and dvds, critic and audience scores, and published reviews. To find out more about the Rotten Tomatoes API, check out the Welcome page and Overview page


  • Supports and tested under Python 2.7.6, 3.3.5, and 3.4.0

  • One-to-one mapping between rtsimple and RT methods.

  • Implements all RT methods.

  • Easy to access data using Python class attributes.

  • Easy to experiment with rtsimple methods inside the Python interpreter.

  • Code tested with unittests, which illustrate the method call syntax.


rtsimple is available on the Python Package Index (PyPI) at

You can install rtsimple using one of the following techniques.

  • Use pip:

pip install rtsimple
  • Download the .zip or .tar.gz file from PyPI and install it yourself

  • Download the source from Github and install it yourself

If you install it yourself, also install requests.


You will need an API key to Rotten Tomatoes to access the API. To obtain a key, follow these steps:

  1. Register for and verify an account.

  2. Log into your account.

  3. Once you are logged in, click on the link to Apply for an API key and follow the instructions.


With the rtsimple package installed and an RT API key, you can start to play with the data.

First, import the package and assign your API_KEY.

>>> import rtsimple as rt

To communicate with the Rotten Tomatoes (RT) API, create an instance of one of the object types, call one of the methods on the instance, and access instance attributes. Use keys to access attribute values that are dictionaries. In this example, we search for movies with Hunger Games in the title, and determine the Rotten Tomatoes id of the second installment in the series, Catching Fire.

>>> movie = rt.Movies()
>>> response ="Hunger Games")
>>> len(movie.movies)
>>> for m in movie.movies:
...     print(m['title'])
The Hunger Games
The Hunger Games: Catching Fire
The Hunger Games: Mockingjay - Part 1
The Hunger Games: Mockingjay - Part 2
>>> movie.movies[1]['id']

Once we have the RT id, we can create a movie instance to represent that movie specifically and examine its attributes.

>>> movie = rt.Movies('771250004')
>>> response =
>>> movie.title
'The Hunger Games: Catching Fire'
>>> movie.mpaa_rating
>>> movie.genres
['Action & Adventure', 'Science Fiction & Fantasy']
>>> movie.runtime
>>> movie.ratings['critics_score']
>>> movie.ratings['audience_score']

For fun, get ratings for the other Hunger Games movies and determine which of the movies is considered by critics to be the best in the series.

Call other instance methods to gather additional information. In this example, we find movies that are considered similar to The Hunger Games: Catching Fire. On the list are the original movie, which isn’t too surprising, and one of the Harry Potter movies, which is a surprise.

>>> response = movie.similar()
>>> len(movie.movies)
>>> for m in movie.movies:
...     print(m['title'])
The Hunger Games
Harry Potter and the Deathly Hallows - Part 1

In addition to extracting detailed information about specific movies, you can get movie and DVD lists from the Rotten Tomatoes API. Suppose you are curious whether the Movies In Theaters list has any movies in common with the DVDs Upcoming list. Note that the RT API lists are updated on a regular basis, so your results may vary from those below.

>>> lst = rt.Lists()
>>> response = lst.movies_in_theaters()
>>> for m in lst.movies[:5]:
...     print(m['title'])
The Legend of Hercules
The Hobbit: The Desolation Of Smaug
Lone Survivor
Anchorman 2: The Legend Continues
>>> response = lst.dvds_upcoming()
>>> for m in lst.movies[:5]:
...     print(m['title'])
Lee Daniels' The Butler
Enough Said
You're Next

For the first 5 entries, there doesn’t appear to be any overlap. For fun, create complete lists of the Movies In Theaters list and DVDs Upcoming list and determine if the lists overlap at all.

Note that you can call methods and get details without explicitly instanciating an object.

>>> response = rt.Movies(771250004).info()
>>> response['alternate_ids']
{'imdb': '1951264'}

If you like this wrapper, and would like access to even more movie and TV data, check out tmdbsimple, a wrapper for The Movie Database API v3.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rtsimple-0.9.0.tar.gz (6.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page