rottentomatoes.com APIrottentomatoes.com ↗
Access Rotten Tomatoes data via 5 endpoints: search movies and shows, get Tomatometer scores, critic and audience reviews, cast, and streaming availability.
curl -X GET 'https://api.parse.bot/scraper/33dfd8d8-fba1-4c3f-860e-6108f06b2e9a/search?query=breaking+bad' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for movies, TV shows, and people by keyword. Returns categorized results with titles, URLs, tomatometer scores, and release years where available.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword or phrase (e.g. 'inception', 'breaking bad'). |
{
"type": "object",
"fields": {
"tv": "array of TV show search results with title, url, tomatometer, and year",
"movies": "array of movie search results with title, url, tomatometer, and year",
"people": "array of celebrity search results with title and url"
},
"sample": {
"data": {
"tv": [
{
"url": "https://www.rottentomatoes.com/tv/breaking_bad",
"year": null,
"title": "Breaking Bad",
"tomatometer": null
}
],
"movies": [
{
"url": "https://www.rottentomatoes.com/m/el_camino_a_breaking_bad_movie",
"year": null,
"title": "El Camino: A Breaking Bad Movie",
"tomatometer": null
}
],
"people": []
},
"status": "success"
}
}About the rottentomatoes.com API
The Rotten Tomatoes API gives you structured access to 5 endpoints covering movie and TV show discovery, detailed metadata, and paginated reviews. The get_movie_details endpoint returns schema.org-structured fields including aggregateRating, actor, director, genre, contentRating, and whereToWatch streaming platforms. The search endpoint returns categorized results across movies, TV shows, and people, each with Tomatometer scores and release years.
Search and Browse
The search endpoint accepts a keyword or phrase via the query parameter and returns three categorized arrays: movies, tv, and people. Movie and TV results include title, url, tomatometer, and year. The browse_movies endpoint lets you page through current movies using a category parameter (movies_at_home or movies_in_theaters) and a sort parameter (popular or newest), returning poster images, aggregateRating, and dateCreated per item. Pagination across both endpoints is cursor-based using an after parameter paired with pageInfo.endCursor.
Movie and TV Show Details
get_movie_details takes a movie slug (the path segment from a Rotten Tomatoes URL, e.g. the_dark_knight) and returns a metadata object conforming to the schema.org Movie type. That object includes name, actor, director, genre, contentRating, dateCreated, and aggregateRating. The response also includes a whereToWatch array listing streaming platforms by name and url, plus an emsId field needed to retrieve reviews. get_tv_show_details works the same way for TV shows, with the metadata object containing containsSeason and numberOfSeasons in place of film-specific fields.
Critic and Audience Reviews
The get_reviews endpoint takes an ems_id obtained from either detail endpoint and returns an array of review objects. Each review includes reviewId, scoreSentiment, reviewQuote, critic, publication, and createDate. You can filter by review_type (critic or user) and control page size with page_count. Pagination uses the same cursor pattern: read pageInfo.endCursor from one response and pass it as after in the next to advance through the full review set.
DTM Analytics Metadata
Both detail endpoints return a dtmData object alongside the schema.org metadata. This object contains analytics-oriented fields like titleName, titleGenre, and titleType, which can be useful for classification tasks or enriching a catalog without parsing the full metadata block.
- Build a movie discovery app that surfaces Tomatometer scores and streaming links from
get_movie_details - Aggregate critic vs. audience sentiment by comparing
scoreSentimentvalues acrossreview_typeinget_reviews - Populate a TV show database with season counts and cast lists from
get_tv_show_details - Track what is currently in theaters vs. available at home using
browse_movieswith thecategoryparameter - Build a people-search feature that maps celebrity names to their Rotten Tomatoes profile URLs via the
searchendpoint - Monitor streaming availability changes for a movie catalog by polling
whereToWatcharrays fromget_movie_details - Collect timestamped critic reviews for sentiment analysis using
createDateandreviewQuotefromget_reviews
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Rotten Tomatoes have an official public developer API?+
How do I get reviews for a specific movie or TV show?+
get_movie_details or get_tv_show_details with the title's slug to retrieve the emsId field. Pass that value as ems_id to get_reviews. Set review_type to critic for professional critic reviews or user for audience reviews. Use page_count to control batch size and after with the returned pageInfo.endCursor to paginate through all results.Does the API return individual episode-level data for TV shows?+
get_tv_show_details returns season count via numberOfSeasons and season structure via containsSeason, but individual episode metadata and episode-level ratings are not exposed. You can fork the API on Parse and revise it to add an episode-level endpoint.What does `dtmData` contain and how is it different from `metadata`?+
metadata is a schema.org-typed object with structured fields like actor, director, aggregateRating, and genre — suitable for display or catalog ingestion. dtmData is an analytics-oriented object with flatter fields like titleName, titleGenre, and titleType. It is primarily useful for classification or tagging pipelines where you want a normalized string representation without parsing nested schema.org structures.Does the API cover box office or revenue data for movies?+
get_movie_details covers ratings, cast, genre, streaming availability, and content rating. You can fork the API on Parse and revise it to add a box office data endpoint if that field is available on the source page.