Package: rotten_tomatoes_client
IntroductionThe Not-So-Private Public
APIClientInstallationSearchBrowse TV
ShowsBrowse
MoviesIntroductionI think Rotten Tomatoes is a pretty neat service. So I wanted to try and
work on a couple projects (like a command line tool) that incorporate
data from Rotten Tomatoes.After a short cursory investigation of existing Rotten Tomatoes Python
clients (likerottentomatoesandrtsimple) I noticed two things:Each client requires an API key for use (which is reasonable)The Rotten Tomatoes API is pretty hard to get access to (less
reasonable).For example:Rotten Tomatoes is no longer issuing API keys at the time of
registration. We will review each application to ensure the usage of
our data aligns with Brand Guidelines and Terms of Service and will
provision keys if approved. There is now a license fee to access the
API details of which will be provided upon application approval. The
approval process may take up to 60 days. Thank you for your
patience.From this GitHub
issue.Thank you for your interest in the Rotten Tomatoes API. API users
have access to our existing API, which provides full access to
Rotten Tomatoes Scores and Reviews Snippets (up to 20), for an
annual fee which starts at $60,000.From this Reddit
thread.The Not-So-Private Public APIIf you go to, say, the“Certified Fresh Movies”
pagealt-textand open up theNetworktab / development console in your browser,
you can see HTTPGETrequests likehttps://www.rottentomatoes.com/api/private/v2.0/browse?minTomato=70&maxTomato=100&maxPopcorn=100&services=amazon%3Bhbo_go%3Bitunes%3Bnetflix_iw%3Bvudu%3Bamazon_prime%3Bfandango_now&certified=true&sortBy=popularity&type=cf-in-theaterswhich returns aJSONresponse that looks like{"counts":{"count":14,"total":14},"debugUrl":"http://rt-client-facade-v2-6-1.aws.prod.flixster.com/list/top-box-office/movies?expand=true&include=%5B%22movieSupplementaryInfo%22%2C%22audienceSummary%22%2C%22affiliates%22%2C%22criticSummary%22%2C%22genres%22%2C%22moviePersonnel%22%2C%22moviePersonnel.actors%22%2C%22moviePersonnel.actors.person%22%5D&page=%7B%22limit%22%3A1000%7D","results":[{"actors":["Chris Pratt","Zoe Saldana","Dave Bautista"],"id":771385707,"mainTrailer":{"id":"11295755","sourceId":"http://link.theplatform.com/s/NGweTC/media/dFLWRKu5WPrE"},"mpaaRating":"PG13","popcornIcon":"upright","popcornScore":90,"posters":{"primary":"https://resizing.flixster.com/Qjh201ZZ1tydptY1QVjOJrYVAis=/130x0/v1.bTsxMjMyMzE1NjtwOzE3MzMyOzEyMDA7NTkxOzg3Ng","thumborId":"v1.bTsxMjMyMzE1NjtwOzE3MzMyOzEyMDA7NTkxOzg3Ng"},"runtime":"2 hr. 17 min.","synopsis":"<em>Guardians of the Galaxy Vol. 2</em>'s action-packed plot, dazzling visuals, and irreverent humor add up to a sequel that's almost as fun -- if not quite as thrillingly fresh -- as its predecessor.","synopsisType":"consensus","theaterReleaseDate":"May 5","title":"Guardians of the Galaxy Vol. 2","tomatoIcon":"certified_fresh","tomatoScore":81,"url":"/m/guardians_of_the_galaxy_vol_2"},{"actors":["Michael Fassbender","Katherine Waterston","Billy Crudup"],"id":771377268,"mainTrailer":{"id":"11295756","sourceId":"http://link.theplatform.com/s/NGweTC/media/fpqxfaxTIQdB"},"mpaaRating":"R","popcornIcon":"upright","popcornScore":61,"posters":{"primary":"https://resizing.flixster.com/S2SZABT3ghBipL-urqBzBqhUs-E=/130x0/v1.bTsxMjM0NTY3NjtqOzE3MzMyOzEyMDA7NTM5OzgwMA","thumborId":"v1.bTsxMjM0NTY3NjtqOzE3MzMyOzEyMDA7NTM5OzgwMA"},"runtime":"2 hr. 0 min.","synopsis":"<em>Alien: Covenant</em> delivers another satisfying round of close-quarters deep-space terror, even if it doesn't take the saga in any new directions.","synopsisType":"consensus","theaterReleaseDate":"May 19","title":"Alien: Covenant","tomatoIcon":"certified_fresh","tomatoScore":71,"url":"/m/alien_covenant"},...]}Essentially, I’ve found these “public” endpoints for 1. Browsing Movies
& TV Shows * Opening This Week, Top DVD & Streaming, New TV Tonight,
etc. 2. Search * Keyword search for movies, franchises, actors, tv
shows, etc.I havenotfound endpoints for a given movie / tv show / actor, which
is annoying.ClientObviously, with a limited (known) API, there will be an equally limited
client interface. Additionally, it goes without saying that since this
is not an officially-supported API, there are no guarantees about the
reliability of this client.Installationpip install rotten_tomatoes_clientSearchThe`searchmethod <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/client.py#L15-L21>`__
takes atermto search for and alimit. The defaultlimitvalue is10.fromrotten_tomatoes_clientimportRottenTomatoesClientresult=RottenTomatoesClient.search(term="Indiana Jones",limit=5)# The result will look something like this# {#     "actorCount": 0,#     "actors": [],#     "criticCount": 0,#     "critics": [],#     "franchiseCount": 1,#     "franchises": [#         {#             "image": "https://resizing.flixster.com/s5UqfnC-acCiofUCK2UAyaNjADM=/fit-in/80x80/v1.bjsxNDMzNTI2O2o7MTczODY7MTIwMDs2MDA7MjYy",#             "title": "Indiana Jones",#             "url": "/franchise/indiana_jones"#         }#     ],#     "movieCount": 31,#     "movies": [#         {#             "castItems": [#                 {#                     "name": "Harrison Ford",#                     "url": "/celebrity/harrison_ford"#                 },#                 {#                     "name": "Karen Allen",#                     "url": "/celebrity/karen_allen"#                 },#                 {#                     "name": "Paul Freeman",#                     "url": "/celebrity/1005456-paul_freeman"#                 }#             ],#             "image": "https://resizing.flixster.com/AGuamVlV_ZyUguJynyXZz5eSapY=/fit-in/80x80/v1.bTsxMTE1NzYxNDtqOzE3NDA5OzEyMDA7MTAxMDsxNTAw",#             "meterClass": "certified_fresh",#             "meterScore": 94,#             "name": "Raiders of the Lost Ark",#             "subline": "Harrison Ford, Karen Allen, Paul Freeman, ",#             "url": "/m/raiders_of_the_lost_ark",#             "year": 1981#         },#         ...#     ],#     "tvCount": 0,#     "tvSeries": []# }Browse TV ShowsThere are only three categories for browsing TV shows (located in theTvBrowsingCategoryenum) *new_tv_tonight*most_popular*certified_freshThe`browse_tv_showsmethod <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/client.py#L23-L31>`__
takesa ``TvBrowsingCategory`value <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L4-L7>`__.
If none is provided, it defaults to using`TvBrowsingCategory.most_popular<https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L6>`__.fromrotten_tomatoes_clientimportRottenTomatoesClient,TvBrowsingCategoryresult=RottenTomatoesClient.browse_tv_shows(category=TvBrowsingCategory.most_popular)# The result will look something like this# {#   "counts": {#     "count": 16,#     "total": 16#   },#   "results": [#     {#       "posters": {#         "primary": "https://resizing.flixster.com/OcgpKual3yhynPR3ZbNl1NfHwUE=/2000x3000/v1.dDsyNTQ3OTI7ajsxNzMyNzsxMjAwOzIwMDA7MzAwMA"#       },#       "title": "Twin Peaks: The Return",#       "tomatoIcon": "certified",#       "tomatoScore": 95,#       "url": "/tv/twin_peaks/s03"#     },#     {#       "posters": {#         "primary": "https://resizing.flixster.com/ON_GjiBNjJ8InbhnRnr0wCNKGAQ=/2048x3072/v1.dDsyNTI5MDY7ajsxNzMyNzsxMjAwOzIwNDg7MzA3Mg"#       },#       "title": "American Gods: Season 1",#       "tomatoIcon": "certified",#       "tomatoScore": 96,#       "url": "/tv/american_gods/s01"#     },#     ...#   ],#   "title": "Most Popular TV on RT"# }Browse MoviesThe`browse_moviesmethod <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/client.py#L23-L31>`__
takesa
``MovieBrowsingQuery`<https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/client.py#L23-L31>`__
that is composed of the following parameters *minimum_rating*
Minimum allowable RottenTomatoes score * Defaults to70*maximum_rating* Maximum allowable RottenTomatoes score * Defaults
to100*services* Alistof any ofthe ``Service`enum
values <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L10-L17>`__
like`Service.amazon<https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L11>`__
or`Service.netflix<https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L14>`__.
* Defaults to all streaming options. *certified_fresh* Abooleanthat represents whether movies that are (or are not)
“Certified Fresh” should be considered. * Defaults toFalse*genres* Alistof any ofthe ``Genre`enum
values <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L37-L49>`__
like`Genre.action<https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L38>`__
or`Genre.comedy<https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L42>`__.
* Defaults to all genres. *sort_by* Can either sort by
popularity or release date usingthe ``SortBy`enum <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L20-L22>`__.
* Defaults to sorting by popularity *category* Represents what
types of movies to filter by, for example, ones that are opening in
theaters, or have recently been released on DVD / streaming. * Takes
any ofthe ``MovieBrowsingCategory`enum
values <https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L25-L34>`__
like`MovieBrowsingCategory.certified_fresh_in_theaters<https://github.com/jaebradley/rotten_tomatoes_client/blob/master/rotten_tomatoes_client/query/parameters/browsing.py#L29>`__.fromrotten_tomatoes_clientimportRottenTomatoesClient,MovieBrowsingQuery,Service,Genre,SortBy,MovieBrowsingCategory# Give me some relatively shitty action, comedy, or romance movies on Netflix or Amazon Prime, sorted by popularityquery=MovieBrowsingQuery(minimum_rating=35,maximum_rating=70,services=[Service.netflix,Service.amazon_prime],certified_fresh=False,genres=[Genre.action,Genre.comedy,Genre.romance],sort_by=SortBy.popularity,category=MovieBrowsingCategory.all_dvd_and_streaming)result=RottenTomatoesClient.browse_movies(query=query)# The result will look something like this# {#   "counts": {#     "count": 32,#     "total": 771#   },#   "results": [#     {#       "id": 10180,#       "title": "10 Things I Hate About You",#       "url": "/m/10_things_i_hate_about_you",#       "tomatoIcon": "fresh",#       "tomatoScore": 61,#       "popcornIcon": "upright",#       "popcornScore": 69,#       "theaterReleaseDate": "Mar 31",#       "dvdReleaseDate": "Oct 12",#       "mpaaRating": "PG13",#       "synopsis": "Julia Stiles and Heath Ledger add strong performances to an unexpectedly clever script, elevating 10 Things (slightly) above typical teen fare.",#       "synopsisType": "consensus",#       "runtime": "1 hr. 37 min.",#       "posters": {#         "thumborId": "v1.bTsxMTIwNzQ3NTtqOzE3NDA5OzEyMDA7MTgwMDsyNDAw",#         "primary": "https://resizing.flixster.com/J0m170tQD8igSYaxp2rtyd5N8wU=/130x0/v1.bTsxMTIwNzQ3NTtqOzE3NDA5OzEyMDA7MTgwMDsyNDAw"#       },#       "actors": [#         "Larisa Oleynik",#         "Julia Stiles",#         "Heath Ledger"#       ]#     },#     {#       "id": 12852,#       "title": "Love Actually",#       "url": "/m/love_actually",#       "tomatoIcon": "fresh",#       "tomatoScore": 63,#       "popcornIcon": "upright",#       "popcornScore": 72,#       "theaterReleaseDate": "Nov 7",#       "dvdReleaseDate": "Apr 27",#       "mpaaRating": "R",#       "synopsis": "A sugary tale overstuffed with too many stories. Still, the cast charms.",#       "synopsisType": "consensus",#       "runtime": "2 hr. 15 min.",#       "mainTrailer": {#         "sourceId": "http://link.theplatform.com/s/NGweTC/media/yHqz_0l_lb0V",#         "id": "11295544"#       },#       "posters": {#         "thumborId": "v1.bTsxMTE3NDgyMjtqOzE3NDA5OzEyMDA7ODAwOzEyMDA",#         "primary": "https://resizing.flixster.com/V2-mrbEXdlXN269WjQ_pcuPpNXQ=/130x0/v1.bTsxMTE3NDgyMjtqOzE3NDA5OzEyMDA7ODAwOzEyMDA"#       },#       "actors": [#         "Bill Nighy",#         "Hugh Grant",#         "Liam Neeson"#       ]#     },#     {#       "id": 2864421,#       "title": "Hoodwinked",#       "url": "/m/1155109-hoodwinked",#       "tomatoIcon": "rotten",#       "tomatoScore": 46,#       "popcornIcon": "spilled",#       "popcornScore": 56,#       "theaterReleaseDate": "Jan 13",#       "dvdReleaseDate": "May 2",#       "mpaaRating": "PG",#       "synopsis": "This fractured fairytale doesn't have the wit or animation quality to compete with the likes of the <i>Shrek</i> franchise.",#       "synopsisType": "consensus",#       "runtime": "1 hr. 20 min.",#       "posters": {#         "thumborId": "v1.bTsxMTIwOTMwNDtqOzE3NDA5OzEyMDA7MTUzNjsyMDQ4",#         "primary": "https://resizing.flixster.com/Nra17Z2DFslffNklaVkXaGmSmw4=/130x0/v1.bTsxMTIwOTMwNDtqOzE3NDA5OzEyMDA7MTUzNjsyMDQ4"#       },#       "actors": [#         "Glenn Close",#         "Anne Hathaway",#         "Jim Belushi"#       ]#     },#     ...#   ]# }