Rotten Tomatoes API

If you followed my series on data binding, then you probably remember me briefly covering the Rotten Tomatoes API in Part 5 Dynamic Data From Rotten Tomatoes. However, since the focus of that post was on data binding and not on the REST APIs, I didn’t go into too much detail.  That said, I am now going to transition to a series on incorporating REST API support into projects that you can build with App Studio, starting with…yep you guessed it, the Rotten Tomatoes API.  It might be worth adding another post with a brief intro to App Studio as well, but for now I am just going to focus on Rotten Tomatoes.


So what exactly is Rotten Tomatoes? is a go to source for reviews and ratings for movies, whether they be in the box office, on dvd, etc.  You can check out what’s new, what’s coming up, and what’s topping the various lists for theaters, dvd, and tv.  All and all, a great resource for movie information, and knowing that, Rotten Tomatoes created an open API from that information.  So, how do you get access to all of that information via the API?  First things first, we need to sign up for an API key to use as authentication when making calls.

You can sign up for an API key at the developer website.  On the page you can see their short description of their API, quoted below.

“The Rotten Tomatoes API provides access to Rotten Tomatoes' ratings and reviews, allowing you to build applications and widgets enriched with Rotten Tomatoes data.  By implementing the Rotten Tomatoes API, here are some of the things your users can do:

  • Access Rotten Tomatoes Critic and Audience ratings and review snippets
  • Get listings for movies that are opening soon and currently in theaters
  • Get listings for movies that are releasing soon and currently available on DVD or streaming

Please note that we only provide a certain level of movie metadata to help with matching our content to your existing movies database.  More detailed movie metadata and high-resolution images will need to be sourced elsewhere.”

Keep that last part about detailed move metadata in mind, and I will comment on it shortly.  Anyways, from that website, you can click on register.  You’ll have to create a username and password, and then give some information about your “company”.  Company could mean a lot of things, but if you plan on publishing an app, you can use your publisher name.  Continuing on, you then need to register your “New Application”.  That part is pretty straight forward too but necessary to get the API key.

After you get the API key taken care you can start making calls and exploring the API itself.  One great way to start is with the IODocs, which allows you to choose from a list of different calls to the API and see a pretty clear and more visual representation of the data that comes back.  Shown below is a list of some of the calls that you can make.


Once you select one of these, you will get the option to “Try It”, where you can customize a couple of the parameters, specifically the number of movies to be returned and the country you want information from.  Once you click the “Try It” button, they will show you the Request URI that was sent, the response headers, and what we care about most, the response body, where all of the magic happens!  The example pictured below is making a call for movies in the box office.



Like I said, this tool goes ahead and puts the URI together for you, and trust me this is a very handy thing!  It’s sort of tedious to work through concatenating the URI yourself.  However, let me very quickly talk about how it works.  Here is the URL that I used in the above images.[apikey]

The base URI for all resources is, so anytime you are looking to make a call you will start with that.  Next comes the kind of call that we are making, which above means we want a list of movies from the box office.  I put that phrase in bold because it comes directly from the URI above.  After that you can include any parameters such as limit and country as above and then your actual API key.

That’s the basics for how building the URI works, but again, I highly recommend using the IODocs that will put together those URIs for you!  Now, let’s take a look at the data that actually comes back from one of these calls.  I am going to focus on calls that return lists of movies because that will be most applicable in the App Studio projects but keep in mind, for more general purposes, you can make calls about specific movies, movie searches, etc.

From a high level, the root object that the API returns include a List of movies objects, a Links2 object, and a string called link_template.  What we really need to focus on here is the list of Movie objects called movies.  Here’s a look at how the Movie object would be defined in C#.

public class Movie
    public string id { get; set; }
    public string title { get; set; }
    public int year { get; set; }
    public string mpaa_rating { get; set; }
    public int runtime { get; set; }
    public string critics_consensus { get; set; }
    public ReleaseDates release_dates { get; set; }
    public Ratings ratings { get; set; }
    public string synopsis { get; set; }
    public Posters posters { get; set; }
    public List<AbridgedCast> abridged_cast { get; set; }
    public AlternateIds alternate_ids { get; set; }
    public Links links { get; set; }

Notice, that this Movie object has a lot of information in it!  This is a good thing.  A lot of this is pretty self explanatory, but some of the highlights and most useful pieces of information I see here are the title, year, mpaa rating, poster (images).  All of the data I just mentioned are simple ints and strings except for the Posters, which is it’s own object.  It is defined like so.

public class Posters
    public string thumbnail { get; set; }
    public string profile { get; set; }
    public string detailed { get; set; }
    public string original { get; set; }

Great!  It has links for four different kinds of images including a lo res thumbnail and a hi res original.  But wait a second.  Remember what Rotten Tomatoes said earlier in their documentation about some movie metadata and resources you will need to get elsewhere?  This is what they mean.  Although you have the ability to seemingly access all of the four different types of posters, they each return the link for the thumbnail.  Here’s an example.

"posters": {
"thumbnail": "",
"profile": "",
"detailed": "",

Notice all of these links end in tmb which represents the thumbnail image.  Although they are only returning the tmb images, you can still manually alter these links to get to the different images by replacing “tmb” with “ori”, “det”, or “pro”.  Just a little trick I have come across Smile  We will see how long that stays available, however.

Alright, so after the posters, we have access to the Links object, which just contains a list of string links, defined below.

public class Links
    public string self { get; set; }
    public string alternate { get; set; }
    public string cast { get; set; }
    public string reviews { get; set; }
    public string similar { get; set; }

Similarly, you have the Ratings object which has different string ratings and int scores.

public class Ratings
    public string critics_rating { get; set; }
    public int critics_score { get; set; }
    public string audience_rating { get; set; }
    public int audience_score { get; set; }

These are the big ones that jump out at me, but at the bottom of the page I will include all of the different c# class, that I generated from json2csharp.  So what would accessing this information look like in code.  Let’s say that our root object is called InTheaterMovies, then to access the list of movies in that object we could simple use.


This would return the list of Movie objects from the root object.  From there, we could than access the title and year for instance like so.



Additionally, we could access the Links and Ratings objects like so.



And then dig in deeper into their properties, and so on.  It is definitely worth while to have a basic understanding of how these objects and data are nested within each other.  However, what better way to learn than by exploring right?  Again, the IODocs are your friend, and I highly recommend starting there!

I hope this gives a more in depth introduction to the Rotten Tomatoes, so that when I move forward with incorporating this API into App Studio projects, it is pretty easy to digest.  Anyways, as always comment below with and questions, comments, or concerns, and feel free to follow me on twitter at @jquickwit.

Comments (1)

  1. Anonymous says:

    I'm just reading up on this stuff, not a huge programmer, but really terrific article!

Skip to main content