API Overview

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.  

To access our Rotten Tomatoes design assets:

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_tmb.jpg",
      "profile": "http://content6.flixster.com/movie/11/13/43/11134356_tmb.jpg",
      "detailed": "http://content6.flixster.com/movie/11/13/43/11134356_tmb.jpg",
      "original": "http://content6.flixster.com/movie/11/13/43/11134356_tmb.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_tmb.jpg",
      "profile": "http://content6.flixster.com/movie/11/13/43/11134356_tmb.jpg",
      "detailed": "http://content6.flixster.com/movie/11/13/43/11134356_tmb.jpg",
      "original": "http://content6.flixster.com/movie/11/13/43/11134356_tmb.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.

40 Comments

  1. Philip Peter3 years ago

    Perfect. I really love this API. Easy to use

  2. Hardik3 years ago

    http://api.rottentomatoes.com/api/public/v1.0.xml?apikey= [ your api key ] is not working

  3. webpaul3 years ago

    Maybe I am wrong but I cannot success in getting data for Italy. I use "it" as the country "code" but I think it is not working because I get "us" or "international" results. Is Italy supported? I have an italian website and I'd love to use this great API.

  4. Steve N.3 years ago

    Hi webpaul, Unfortunately we do not have data for Italy at this time and plans for adding additional countries are still very early (read: we won't be adding any additional countries this year)

  5. MichaelToler3 years ago

    Hardik, the issue is that the URL is wrong. It should be v1.0.json instead of v1.0.xml. They say that earlier in the page, but the link example there is screwed up.

  6. MichaelToler3 years ago

    And now I look like an idiot.

    The xml example was shown as "if we were to support xml, it would look like ...". I think we both copied the wrong link to being with.

  7. webpaul3 years ago

    Thank you Steve. Then I'll try to create some cool features on my website with your API without references to Italy (poster, trailers, cast...)

    I'll wait for new updates

  8. simonxu3 years ago

    excellent job! i hope i will create a great web app by your work,thanks again.

  9. Sivar3 years ago

    Is there a possibility of adding functionality to specify the year of release?

    For example, if I search for:

    Alice In Wonderland
    

    The first result is the 2010 movie by Tim Burton.

    If I search for:

    Alice In Wonderland 1951
    

    I still get the Tim Burton movie.

    True, I can loop through all the results, but it would be helpful to be able to usually rely on the first result being good when enough information is provided to the search.

    I envision the feature as an optional query parameter, not part of the title:

    api.rottentomatoes.com/[...]?q=**Alice%20In%20Wonderland**&**year=_1951_**&page_limit=1&apikey=[...]
    

    One reason is to avoid ambiguities that can arise from, for example, "2012 2009" (2012 came out in 2009) Sometimes the years may differ. For example, IMDB things that "300" is a 2006 movie. RottenTomatoes thinks it's a 2007 movie. A solution is to order results by distance from the specified year (so Alice in Wonderland with year=1950 would still return the 1951 version first). Another solution is to look +1 year and -1 year and return the first result found if there is no exact year match.

  10. lighthurst3 years ago

    Thanks for the API. What would be even better is adding functionality to search all movies reviewed by a certain critic. Yes, yes, yes!

  11. teddy483 years ago

    I cant access the api itz giving a message {"error":"Not Authorized"} . ??

  12. Steve N.3 years ago

    Hi teddy48,

    This isn't the best place to ask for help with errors. I would suggest you post your question in the forums. In any case, can you provide info on how you are making the call that is giving you the "Not Authorized" error? Please make sure to include your apikey as a query parameter. For example: http://api.rottentomatoes.com/api/public/v1.0/movies/770672122.json?apikey=[your_api_key]

  13. Max Power2 years ago

    When will the xml API be ready ? I have an application that utilises xml and the api i'm using now is dumping the xml in favour of jasonp

  14. Sudeep2 years ago

    I heard that rotten tomato data is limited to 10000 hit which it will be consumed by 5 users at the same time???

    Is that correct?

    Looking forward to your response.

    Thanks Sudeep

  15. Rothwild2 years ago

    When will the XML-Api be ready? Have you an release date for us? :)

  16. webpaul2 years ago

    What about Actors and Actresses info? Aren't there any API to have a pict and a brief description of them? It would be great!

  17. Yaniv Ben-Yehuda2 years ago

    Can the api be accessed via jsonp? I would like to access it from the client side without a need to a proxy gateway

  18. sjrasimons2 years ago

    It would be nice if the example URLs would be auto-filled with your API key if you are logged in (or a list for the different API keys)?

  19. sjrasimons2 years ago

    never mind, I was too quick to judge, the IO Docs do just that, thank you, great API

  20. krishna2 years ago

    is there any way to search with actor id (i.e. if we mention the actor id then the response contains actor movies or actor images/stills in different movies i.e. actor image database )

  21. Phil Pearl2 years ago

    Is it possible to search by alternate title? For example "Live Free or Die Hard" is called "Die Hard 4.0" in the UK. You have that information on the website (http://www.rottentomatoes.com/m/live_free_or_die_hard/, bottom right corner), but I can't find it on the API, and searching for "Die Hard 4.0" yields no results.

  22. Shubhang Verma2 years ago

    I used the php Code above with my api key but am always getting Unable Unable to parse Json always.

  23. jay2 years ago

    Hi sir, Thanks for releasing this api. My question is: How can I get the Theatre/Cinema hall/Picture hall name with city based in USA for searched movie.

  24. abhisom2 years ago

    "synopsis" is empty for most of movies( troy ,blade runner ,spiderman etc ),i can't fetch data about these movies,even if the data is given in site .please fix this issue.

  25. Bobby Duvali2 years ago

    Your whole API isn't working...

  26. Rizki1 year ago

    Hey i've already try : http://api.rottentomatoes.com/api/public/v1.0/lists/movies/box_office.json?apikey=[MYKEY] But it still cannot be loaded, also when i tried to access that link, i've got message like this: {"error":"Account Inactive"}

    Need Help. Thanks

  27. jpotts181 year ago

    I am getting a 403 when I hit the http://api.rottentomatoes.com/api/public/v1.0/movies.json?apikey={key}

    1. {
    2. error: "Account Inactive"
    3. }

    I signed up yesterday night, and I have been sent two emails. My application was confirmed, and my key was mailed to me. I have clicked all of the confirmation links but I am still unauthorized. Please help.

  28. shery1 year ago

    can you use this api to display showtimes of movies in theaters?

    thanks

  29. ngugi1 year ago

    Hi, How can I get rid of the white space lines being displayed in the JSON file that is returned after searching.

  30. SoftGooey1 year ago

    I also need actor information.

  31. Maximilian Litteral1 year ago

    When was the last time this API was updated? I was going to make an application using this info, but they don't give out much information. Wheres actor info? director? Images, and the rest of the data that movies should have. An actor ID doesn't help If we cant use it to find the actor and get their information. Please update

  32. leegee1 year ago

    Not as useful as I hoped. I do like the ability to get the RT score, but I also wanted to get a list of the films I have marked as 'want to see' -- is that going to be possible any time soon, or should I just screen scrape? Thanks, Lee

  33. Rohir Naik1 year ago

    i cannot access for indian movies in GOA if i put ZIP correctly in show timmings. Why?

  34. ginahill1 year ago

    I'm trying to get the next and previous to work and can't figure out exactly what the link should be??? Please help - I want to add a next and previous to my page and make it show the next and previous movies.

  35. Ben11 months ago

    For anyone wondering how to make a jsonp request, just add callback=? to the end of your api string.

  36. ivanka11 months ago

    I can loop through all the results, but it would be helpful to be able to usually rely on the first result being good when enough information is provided to the search. <a href=http://marotravel.com/pulau-pramuka-murah/>Pulau Pramuka</a>

  37. Muskie5 months ago

    I too am getting

    {"error":"Account Inactive"}

    I never stopped using the API, how to do I reactivate my account?

  38. Strahan5 months ago

    To the people getting account inactive, I too had that problem. I used the link template exactly as I received, but the template doesn't have apikey so be sure to add apikey=[your key]. Once I added that, it worked fine.

  39. dinnagonzales2 months ago

    For everyone getting the error, you should remove the brackets and it should work.

    http://api.rottentomatoes.com/api/public/v1.0.json?apikey=XXXXXXXXXXXXXXXXX

  40. zgski1 month ago

    "This resource does not support GET requests at this time."

Please sign in to post a comment.