The Rotten Tomatoes API is RESTful web service that was designed to be easy to explore and use. The base URI to access all resources is http://api.rottentomatoes.com/api/public/v1.0. It is our hope that through the base URI, a developer getting started with our API will be able to reach and manipulate our APIs without reading through multiple pages of documentation. This is accomplished by linking related resources and providing instructions on how to use each representation (link templates) in the response itself.

For a dynamic view of our documentation, try our IO Docs!  IO Docs allows you to make live calls to our APIs while getting a stronger understanding for all of the resources and parameters involved.  

A Quick Dive into the API

Let's take a quick exploratory dive into the API and see this thing in action. To start out on our journey, simply register for a Rotten Tomatoes API key, select your favorite browser and navigate to the "homepage" of our API with your API key appended at the end. For example: http://api.rottentomatoes.com/api/public/v1.0.json?apikey=[your_api_key] Replace [your_api_key] with your own API key. Notice the extension '.json' at the end of the URL. We currently support responses in JSON, with future plans to support other data formats. In the future, for example, if we supported xml, you would be able to hit http://api.rottentomatoes.com/api/public/v1.0.xml?apikey=[your_api_key] .

You should get a response like below:

http://api.rottentomatoes.com/api/public/v1.0.json?apikey=[your_api_key]

{"links": {
  "lists": "http://api.rottentomatoes.com/api/public/v1.0/lists.json",
  "movies": "http://api.rottentomatoes.com/api/public/v1.0/movies.json"
}}

The response provides us with links to the two main resources provided by the Rotten Tomatoes API, lists and movies. Let's hit the movies URL with our API key:

http://api.rottentomatoes.com/api/public/v1.0/movies.json?apikey=[your_api_key]

{"link_template": "http://api.rottentomatoes.com/api/public/v1.0/movies.json?q={search-term}&page_limit={results-per-page}&page={page-number}"}

This endpoint provides us with a 'link_template' to fill out. This is our API to search for movies. Let's try it with one of my favorite movies, Toy Story 3. Make sure to URI encode your queries! http://api.rottentomatoes.com/api/public/v1.0/movies.json?apikey=[your_api_key]&q=Toy+Story+3&page_limit=1

{
  "total": 2,
  "movies": [{
    "id": "770672122",
    "title": "Toy Story 3",
    "year": 2010,
    "mpaa_rating": "G",
    "runtime": 103,
    "critics_consensus": "Deftly blending comedy, adventure, and honest emotion, Toy Story 3 is a rare second sequel that really works.",
    "release_dates": {
      "theater": "2010-06-18",
      "dvd": "2010-11-02"
    },
    "ratings": {
      "critics_rating": "Certified Fresh",
      "critics_score": 99,
      "audience_rating": "Upright",
      "audience_score": 91
    },
    "synopsis": "Pixar returns to their first success with Toy Story 3. The movie begins with Andy leaving for college and donating his beloved toys -- including Woody (Tom Hanks) and Buzz (Tim Allen) -- to a daycare. While the crew meets new friends, including Ken (Michael Keaton), they soon grow to hate their new surroundings and plan an escape. The film was directed by Lee Unkrich from a script co-authored by Little Miss Sunshine scribe Michael Arndt. ~ Perry Seibert, Rovi",
    "posters": {
      "thumbnail": "http://content6.flixster.com/movie/11/13/43/11134356_mob.jpg",
      "profile": "http://content6.flixster.com/movie/11/13/43/11134356_pro.jpg",
      "detailed": "http://content6.flixster.com/movie/11/13/43/11134356_det.jpg",
      "original": "http://content6.flixster.com/movie/11/13/43/11134356_ori.jpg"
    },
    "abridged_cast": [
      {
        "name": "Tom Hanks",
        "characters": ["Woody"]
      },
      {
        "name": "Tim Allen",
        "characters": ["Buzz Lightyear"]
      },
      {
        "name": "Joan Cusack",
        "characters": ["Jessie the Cowgirl"]
      },
      {
        "name": "Don Rickles",
        "characters": ["Mr. Potato Head"]
      },
      {
        "name": "Wallace Shawn",
        "characters": ["Rex"]
      }
    ],
    "alternate_ids": {"imdb": "0435761"},
    "links": {
      "self": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122.json",
      "alternate": "http://www.rottentomatoes.com/m/toy_story_3/",
      "cast": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/cast.json",
      "clips": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/clips.json",
      "reviews": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/reviews.json",
      "similar": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/similar.json"
    }
  }],
  "links": {
    "self": "http://api.rottentomatoes.com/api/public/v1.0/movies.json?q=Toy+Story+3&page_limit=1&page=1",
    "next": "http://api.rottentomatoes.com/api/public/v1.0/movies.json?q=Toy+Story+3&page_limit=1&page=2"
  },
  "link_template": "http://api.rottentomatoes.com/api/public/v1.0/movies.json?q={search-term}&page_limit={results-per-page}&page={page-number}"
}

This will return two movies that matched the query 'Toy Story 3'. The 'total' attribute shows that there are a total of 2 results, but only one is shown since the page_limit parameter was set to 1. The result includes links to the movie on the Rotten Tomatoes website (the alternate link), and a link to another api resource to the movie itself (the self link). We'll use this link, the self link, to make a call to the movie itself:

http://api.rottentomatoes.com/api/public/v1.0/movies/770672122.json?apikey=[your_api_key]

{
  "id": 770672122,
  "title": "Toy Story 3",
  "year": 2010,
  "genres": [
    "Animation",
    "Comedy",
    "Kids & Family",
    "Science Fiction & Fantasy"
  ],
  "mpaa_rating": "G",
  "runtime": 103,
  "critics_consensus": "Deftly blending comedy, adventure, and honest emotion, Toy Story 3 is a rare second sequel that really works.",
  "release_dates": {
    "theater": "2010-06-18",
    "dvd": "2010-11-02"
  },
  "ratings": {
    "critics_rating": "Certified Fresh",
    "critics_score": 99,
    "audience_rating": "Upright",
    "audience_score": 91
  },
  "synopsis": "Pixar returns to their first success with Toy Story 3. The movie begins with Andy leaving for college and donating his beloved toys -- including Woody (Tom Hanks) and Buzz (Tim Allen) -- to a daycare. While the crew meets new friends, including Ken (Michael Keaton), they soon grow to hate their new surroundings and plan an escape. The film was directed by Lee Unkrich from a script co-authored by Little Miss Sunshine scribe Michael Arndt. ~ Perry Seibert, Rovi",
  "posters": {
    "thumbnail": "http://content6.flixster.com/movie/11/13/43/11134356_mob.jpg",
    "profile": "http://content6.flixster.com/movie/11/13/43/11134356_pro.jpg",
    "detailed": "http://content6.flixster.com/movie/11/13/43/11134356_det.jpg",
    "original": "http://content6.flixster.com/movie/11/13/43/11134356_ori.jpg"
  },
  "abridged_cast": [
    {
      "name": "Tom Hanks",
      "characters": ["Woody"]
    },
    {
      "name": "Tim Allen",
      "characters": ["Buzz Lightyear"]
    },
    {
      "name": "Joan Cusack",
      "characters": ["Jessie the Cowgirl"]
    },
    {
      "name": "Don Rickles",
      "characters": ["Mr. Potato Head"]
    },
    {
      "name": "Wallace Shawn",
      "characters": ["Rex"]
    }
  ],
  "abridged_directors": [{"name": "Lee Unkrich"}],
  "studio": "Walt Disney Pictures",
  "alternate_ids": {"imdb": "0435761"},
  "links": {
    "self": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122.json",
    "alternate": "http://www.rottentomatoes.com/m/toy_story_3/",
    "cast": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/cast.json",
    "clips": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/clips.json",
    "reviews": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/reviews.json",
    "similar": "http://api.rottentomatoes.com/api/public/v1.0/movies/770672122/similar.json"
  }
}

A wealth of information is provided on Toy Story 3. Of note is the links at the bottom of the response. It again has a link to the movie on the Rotten Tomatoes website, and links titled 'cast' and 'reviews'. For now, our journey ends, but I wonder what those links will lead to...

The API Dive Summarized

We hoped you picked up these pearls of wisdom from that quick dive into the API.

• Exploration: Exploring the API and what it provides is a quick process that starts with visiting the API "homepage" with your API key
• Links: Resources are linked together. Look at the 'links' section of a response to see all the related resources.
• Link Templates: If a resource has extra parameters available, they will be spelled out in the 'link_templates' section

If you need further reference, take a look at our sample code and our API reference. Bon Voyage! Have a fun time working on the Rotten Tomatoes API!