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

Parameter	Required	Default	Description
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}"

}

version 3 as of 2 years ago by Steve N.

27 Comments

Omertron – 2 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.
Omertron – 2 years ago

Nevermind, I see the actual response returned contains an "id" field.
Steve N. – 2 years ago

Thanks, the doc needs to be updated to reflect that field
Rodrigo – 2 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
Steve N. – 2 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
Rodrigo – 2 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
Steve N. – 2 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.
jonbcamposYahoo – 2 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.
Steve N. – 2 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.
Rodrigo – 2 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
Steve N. – 2 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.
Collin Ruffenach – 2 years ago

Is there a way to make queries more explicitly? For instance only drama movies in the 1970's or something?
Bruce – 2 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
Steve N. – 2 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/
nonzenze – 2 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}
bbougie – 2 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!
Curtis Gibby – 2 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
Muskie – 2 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.
Steve N. – 2 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.
pangea – 1 year ago

Is there a way to search or retrieve the list of movies between a fromDate and toDate?
simonxu – 1 year 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.
longplay – 1 year 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!
Rothwild – 5 months 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? ;)
Ariel – 4 months 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?
schweini – 1 month 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?
Julien Lamarche – 4 weeks 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)
Julien Lamarche – 4 weeks ago

Oups, guess I'll redo my api key.

Please sign in to post a comment.

Movies Search

URL

Parameters

Example Call and Response

27 Comments

Docs Navigation