Rotten Tomatoes APIrottentomatoes.com ↗
Access Rotten Tomatoes data via 5 endpoints: search movies and shows, get Tomatometer scores, critic and audience reviews, cast, and streaming availability.
What is the Rotten Tomatoes 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.
curl -X GET 'https://api.parse.bot/scraper/33dfd8d8-fba1-4c3f-860e-6108f06b2e9a/search?query=inception' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace rottentomatoes-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Rotten Tomatoes SDK — search, browse, details, and reviews."""
from parse_apis.Rotten_Tomatoes_API import RottenTomatoes, BrowseCategory, Sort, ReviewType, ContentNotFound
rt = RottenTomatoes()
# Search across movies, TV, and people
results = rt.movies.search(query="inception")
for item in results.movies[:3]:
print(item.title, item.url, item.tomatometer)
# Browse popular movies at home
for movie in rt.movies.browse(category=BrowseCategory.AT_HOME, sort=Sort.POPULAR, limit=5):
print(movie.name, movie.year, movie.position, movie.url)
# Get full details for a specific movie and list its critic reviews
dark_knight = rt.movies.get(slug="the_dark_knight")
print(dark_knight.slug, dark_knight.ems_id)
for review in dark_knight.reviews.list(review_type=ReviewType.CRITIC, limit=3):
print(review.review_id, review.score_sentiment, review.review_quote)
# Get a TV show and list user reviews
breaking_bad = rt.tv_shows.get(slug="breaking_bad")
print(breaking_bad.slug, breaking_bad.ems_id)
for review in breaking_bad.reviews.list(review_type=ReviewType.USER, limit=3):
print(review.review_id, review.score_sentiment, review.create_date)
# Typed error handling for a non-existent slug
try:
rt.movies.get(slug="nonexistent_movie_xyz_999")
except ContentNotFound as exc:
print(f"Not found: {exc.slug}")
print("exercised: movies.search / movies.browse / movies.get / movie.reviews.list / tv_shows.get / tvshow.reviews.list")
Search for movies, TV shows, and people by keyword. Returns categorized results with titles, URLs, tomatometer scores, and release years where available. Results are not paginated; the site returns a fixed set of top matches per category.
| 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/cruel_intentions",
"year": null,
"title": "Cruel Intentions",
"tomatometer": null
}
],
"movies": [
{
"url": "https://www.rottentomatoes.com/m/inception",
"year": null,
"title": "Inception",
"tomatometer": null
}
],
"people": []
},
"status": "success"
}
}About the Rotten Tomatoes API
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.
The Rotten Tomatoes API is a managed, monitored endpoint for rottentomatoes.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when rottentomatoes.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official rottentomatoes.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.