Movies Search

The movies search endpoint for plain text queries. Allows you to search for movies!

URL

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

Parameters

ParameterRequiredDefaultDescription
q false The plain text search query to search for a movie. Remember to URI encode this!
page_limit false 30 The amount of movie search results to show per page
page false 1 The selected page of movie search results

Example Call and Response

http://api.rottentomatoes.com/api/public/v1.0/movies.json?apikey=[your_api_key]&q=Jack&page_limit=1

{
  "total": 591,
  "movies": [{
    "title": "Jack and Jill",
    "year": 2011,
    "runtime": "",
    "release_dates": {"theater": "2011-11-11"},
    "ratings": {
      "critics_score": -1,
      "audience_score": 90
    },
    "synopsis": "",
    "posters": {
      "thumbnail": "http://images.rottentomatoescdn.com/images/redesign/poster_default.gif",
      "profile": "http://images.rottentomatoescdn.com/images/redesign/poster_default.gif",
      "detailed": "http://images.rottentomatoescdn.com/images/redesign/poster_default.gif",
      "original": "http://images.rottentomatoescdn.com/images/redesign/poster_default.gif"

    },
    "abridged_cast": [
      {
        "name": "Al Pacino",
        "characters": []
      },
      {
        "name": "Adam Sandler",
        "characters": []
      },
      {
        "name": "Katie Holmes",
        "characters": []
      }
    ],
    "links": {
      "self": "http://api.rottentomatoes.com/api/public/v1.0/movies/771205893.json",
      "alternate": "http://www.rottentomatoes.com/m/jack_and_jill_2011/"

    }
  }],
  "links": {
    "self": "http://api.rottentomatoes.com/api/public/v1.0/movies.json?q=Jack&page_limit=1&page=1",
    "next": "http://api.rottentomatoes.com/api/public/v1.0/movies.json?q=Jack&page_limit=1&page=2"
  },
  "link_template": "http://api.rottentomatoes.com/api/public/v1.0/movies.json?q={search-term}&page={page-number}&page_limit={results-per-page}"

}

30 Comments

  1. Omertron3 years ago

    How do I get the movie-id of the movie from the movie information?
    I'll need the movie-id to pass to Movie Info, Movie Cast, etc.

  2. Omertron3 years ago

    Nevermind, I see the actual response returned contains an "id" field.

  3. Steve N.3 years ago

    Thanks, the doc needs to be updated to reflect that field

  4. Rodrigo3 years ago

    I couldn't find any field where we can get the Genre of the movie that I can see on the RottenTomatoes web page.

    Am I missing it or it is something that is not available yet? If so do you have an idea when this field will be added on the response?

    Thanks

    Rodrigo

  5. Steve N.3 years ago

    Hi Rodrigo, We don't show the genre of the movie in the Movies Search endpoint. This endpoint is meant to provide a quick overview of search results. To get more detailed info about the movie (like the genre), you can make a request to get the detailed information about the movie in the links.self attribute. In the example above, that would be: http://api.rottentomatoes.com/api/public/v1.0/movies/771205893.json

  6. Rodrigo3 years ago

    Cool Steve. Great job by the way. On the same token, do you have an example where I can pass a list of movies ids and retrieve the information. I am asking because I am developing a mobile app for Iphone and I want the user to search for movies and mark it as "watched" this movie will go to my internal database. Can I store all the movie information on my database so the user will have a much faster access to retrieve these movies, otherwise I will have to pass a list of movies ids to the api and retrieve the information. Plus if lots of people by this app, I am afraid the search calls will exceed the rate limit once the search is done when the user starts type the movie name, right now I am limiting from the beginning of the movie title . That is why I asked if I can have my own database and I would get the updates from the API.

    Please let me know what is the best way to handle this.
    Thanks
    Rodrigo

  7. Steve N.3 years ago

    Hi Rodrigo,
    We don't currently support the feature you request - I've created a thread in the Feature Requests forum for your requested feature: http://developer.rottentomatoes.com/forum/read/112962
    Please also check the Terms of Service (http://developer.rottentomatoes.com/page/read/API_Terms_of_Use) specifically the section on "archive and display"
    Let's move any further discussion into the forums as these comments are intended for the Movies Search Endpoint.

  8. jonbcamposYahoo3 years ago

    Can we get a list of all the attributes and subattributes?

    some calls give multiple release dates and I'm wondering if there is a list of all the possible attributes.

  9. Steve N.3 years ago

    There are currently two possible attributes for release_dates; release_dates.theater and release_dates.dvd
    A list of possible attributes is a good idea. We'll try to roll that out eventually.

  10. Rodrigo3 years ago

    Hi Steve, I used this link to get some more info about the movies: http://api.rottentomatoes.com/api/public/v1.0/movies/771205893.json but the synopsis is blank.

    Could you please point me to the right call where I can get the synopsis for a specific movie?

    Thanks
    Rodrigo

  11. Steve N.3 years ago

    Hi Rodrigo, please take a look at this thread: http://developer.rottentomatoes.com/forum/read/113197
    To summarize: due to a licensing issue, we can only provide the movie synopses for more recent movies.

  12. Collin Ruffenach3 years ago

    Is there a way to make queries more explicitly? For instance only drama movies in the 1970's or something?

  13. Bruce3 years ago

    How do I search for a specific movie that was remade. For example I want the details for True Grit but I want the 1969 version. Is there a way to construct the query to get this? or do I have to loop through all the returned data and compare fields to find the one I want

  14. Steve N.3 years ago

    Hi Bruce, you'll have to do the latter. The search endpoint for the API is backed by the same search that powers the Rotten Tomatoes website, which is skewed toward more recent and more active movies.

    If you're curious, we have a blog post detailing how our search is implemented: http://root.rottentomatoes.com/2011/03/15/search-for-the-perfect-tomato/

  15. nonzenze3 years ago

    Hi, can we search by IMDB id or have a table that translates IMDB -> RT?

    You already have the functionality baked in for: http://www.rottentomatoes.com/alias/?type=imdbid&s=${IMDB}

  16. bbougie3 years ago

    Hi, is there a reason why the movie search only returns data if the title (&q=title) is exact and in the exact case. (Example: "The Alamo" is different than "the alamo" or just "alamo")

    In the example it shows that just "&q=Jack " returns title "Jack and Jill"

    Am I missing something?

    Thanks for your help!

  17. Curtis Gibby3 years ago

    I run a grammar blog at BadApostrophes.com, and unfortunately, I've spotted an unnecessary apostrophe here in this documentation. In the opening paragraph, "Let's you search for movies!" doesn't need an apostrophe.

    I've written this up at http://www.badapostrophes.com/2011/08/lets-have-a-bad-apostrophe-intervention/ , but I'll be happy to update my post if you fix your punctuation problem.

    Thanks, Curtis Gibby

  18. Muskie3 years ago

    My search code based on this example is no longer returning data for any data I seem to pass in. For the Outlaw Josey Wales I got some error message which tried to redirect me to this link:

    http://209.237.233.58/api/public/v1.0/movies/?apikey=shsxnfe3v2ggydvua7u2mtt8&q=The+Outlaw+Josey+Wales

    It appears you have made changes to your API but not let developers who were using it know or updated this documentation.

  19. Steve N.3 years ago

    Hi Muskie, We haven't made any changes recently. What is the call that you are making? I was able to make a successful call with http://api.rottentomatoes.com/api/public/v1.0/movies/?apikey=[my_api_key]&q=The+Outlaw+Josey+Wales Also, could you make a post in the bug forums. This isn't the best place to carry on a discussion about a bug.

  20. pangea2 years ago

    Is there a way to search or retrieve the list of movies between a fromDate and toDate?

  21. simonxu2 years ago

    the parameter q is the to match the movie name,am i right? because i set q equals to 'will smith',the returned data has only 4 movies.

  22. longplay2 years ago

    Title matching seems to be a bit hit and miss, for example, Piranha 3DD returns zero results, dropping to Piranha 3D gets 8 results, including Piranha 3DD!

  23. Rothwild1 year ago

    It would be very useful to send beneath the movie title the year like

    http://api.rottentomatoes.com/api/public/v1.0/movies/?apikey=[my_api_key]&q=Avatar&y=2009

    is this a future feature? Perhaps? ;)

  24. Ariel1 year ago

    Whenever I pass a page number higher than 25 de API complains. Why is it forbidden to go past that number? Is there a way to access all results from a query?

  25. schweini1 year ago

    Is there some way to 'quote' search term, in order to get a shorter result-set?

    E.g.: searching for "to the wonder" results in 494 hits. All of them containing the word 'wonder' in some form or another - but many dont have an "to" or even "the" in their title!

    I would like to, google-style search for EXACTLY "to the wonder". Is this possible?

  26. Julien Lamarche12 months ago

    I have the same issue as schweini in post #25. Searching for "Pain+&+Gain+2013" gives 338 results. http://api.rottentomatoes.com/api/public/v1.0/movies.json?apikey=f5j7vv8nmzhfa38qbx4b5gmg&q=Pain+&+Gain+2013 , with movies even like "The Painting" (although it does come up as the first result hit)

  27. Julien Lamarche12 months ago

    Oups, guess I'll redo my api key.

  28. danial11 months ago

    Is there any specific ordering for the returned result?

  29. lafseo6 months ago

    You hunger your action to be of a creature waving hellos applauses, move the icon by elevating the husband's extremity a small. And the http://www.boomerangreview.com/ also be provided very good information about movie reviews and audio reviews.

  30. naren5 months ago

    how do i use the api in my website narenbruce@gmail.com answer plz.

Please sign in to post a comment.