unofficial-rottentomatoes

Unofficial Rotten Tomatoes Library

This unofficial library provides access to movie and TV show information from Rotten Tomatoes. It enables users to retrieve various details such as ratings, reviews, and additional insights, facilitating seamless interaction with Rotten Tomatoes data.

Project in progress ...

Prerequisites

• Node.js >= 18.x
• Yarn >= 1.x

Installation

Using npm

npm install unofficial-rottentomatoes

Using yarn

yarn add unofficial-rottentomatoes

📚 Documentation

Browse Function Documentation

The browse function retrieves a list of media items based on specified filter criteria. This can include ratings, genres, categories, and other parameters defined in the BrowseFilterSchema.

Usage Example

const filter = {
  categories: 'movies_in_theaters',
  genres: ['action', 'comedy'],
  ratings: ['pg_13'],
  audience: ['verified_hot'],
  critics: ['certified_fresh'],
  affiliates: ['netflix'],
  sortBy: 'sort:newest',
  pagination: {
    page: 1
  },
}
const results = await browse(filter)

Browse Filter Schema

The BrowseFilterSchema defines the structure of the data used in the browse function.

Field	Type	Possible Values	Description
categories	BrowseCategories	'movies_in_theaters', 'movies_at_home', 'movies_coming_soon', 'tv_series_browse'	The selected category to filter media items. You can choose one.
genres	Array<BrowseGenre>	['action', 'adventure', 'animation', 'biography', 'comedy', 'crime', 'documentary', 'drama', 'entertainment', 'faith_and_spirituality', 'fantasy', 'game_show', 'health_and_wellness', 'history', 'holiday', 'horror', 'house_and_garden', 'kids_and_family', 'lgbtq', 'music', 'musical', 'mystery_and_thriller', 'nature', 'news', 'reality', 'romance', 'sci_fi', 'short', 'soap', 'special_interest', 'sports', 'stand_up', 'talk_show', 'travel', 'variety', 'war', 'western']	A list of genres to filter media items.
ratings	Array<BrowseRating>	['g', 'pg', 'pg_13', 'r', 'nc_17', 'nr', 'ur']	A list of ratings to filter media items (e.g., ['pg_13']).
audience	Array<BrowseAudience>	['spilled', 'upright', 'verified_hot']	A list of audience types to filter media items.
critics	Array<BrowseCritic>	['certified_fresh', 'fresh', 'rotten']	A list of critic ratings to filter media items.
affiliates	Array<BrowseAffiliate>	['apple-tv-plus', 'disney-plus', 'hulu', 'netflix', 'paramount-plus', 'peacock', 'prime-video']	A list of affiliates to filter media items.
sortBy	BrowseSortBy	'sort:popular', 'sort:newest', 'sort:top_box_office', 'sort:a_z', 'sort:critic_highest', 'sort:critic_lowest', 'sort:audience_highest', 'sort:audience_lowest'	The sort option for the results. Choose one value as a string.
pagination	BrowsePagination	{ page: number }	An object specifying pagination options such as page and limit.

Browse Response Schema

The response from the browse function follows the structure outlined below, which includes media details such as the ID, title, scores, media type, and more.

Field	Type	Description
id	NullOr(String)	The unique identifier for the media item. May be null if not available.
title	NullOr(String)	The title of the media item. May be null if not available.
criticsScore	NullOr(NumberFromString)	The critic's score, if available, parsed as a number from a string. May be null if not available.
audienceScore	NullOr(NumberFromString)	The audience score, if available, parsed as a number from a string. May be null if not available.
mediaType	NullOr(String)	The type of media (e.g., "movie" or "tv"). May be null if not available.
poster	NullOr(String)	The URL of the media poster image. May be null if not available.
releaseDate	String	The release date of the media item, formatted as a string.

Search for Movies or TV Shows

Utilize the search function to find movies or TV shows by their title. This function returns a list of relevant results based on the search query.

import { search } from 'unofficial-rottentomatoes'

const q = 'Harry Potter and the deathly hallows 2'
const results = await search(q)

Search Response Schema

The SearchSchema defines the structure of the data returned by the search API. Below is a detailed description of each field within the schema:

Field	Type	Description
id	String or null	Unique identifier for the search result.
title	String or null	Title of the movie or TV show.
cast	Array of Strings or null	Array of cast members.
year	Number (from string) or null	Release year as a number.
score	Number (from string) or null	Rating score as a number.
mediaType	String or null	Type of media (e.g., movie, TV show).
poster	String or null	URL of the poster image.

Get Extra Content

Utilize the getExtraContent function to retrieve additional information about a movie or TV show.

import { getExtraContent } from 'unofficial-rottentomatoes'

const id = 'm/harry_potter_and_the_deathly_hallows_part_2'
const result = await getExtraContent(id)

ExtraContent Response Schema

The ExtraContentSchema defines the structure for the additional content retrieved for a media item. Below are the details of each field in the schema:

Field	Type	Description
synopsis	NullOr(String)	A brief summary of the media item's plot or storyline.
castAndCrew	NullOr(Array)	An array of objects containing details about cast and crew. Each object includes:
	- name: String	The name of the cast or crew member.
	- role: String	The role of the individual (e.g., actor, director).
	- poster: String	The URL of the individual's poster image.
	- id: String	The unique identifier for the cast or crew member.
director	NullOr(Array)	An array of directors associated with the media item.
producer	NullOr(Array)	An array of producers associated with the media item.
seasons	NullOr(Array)	An array of seasons for TV shows, structured according to SeasonSchema.
screenwriter	NullOr(Array)	An array of screenwriters associated with the media item.
distributor	NullOr(String)	The name of the distributor for the media item.
productionCompanies	NullOr(Array)	An array of production companies involved in creating the media item.
network	NullOr(String)	The network that aired the media item (for TV shows).
rating	NullOr(String)	The rating of the media item (e.g., PG, R).
genres	NullOr(Array)	An array of genres associated with the media item.
originalLanguage	NullOr(String)	The original language in which the media item was produced.
releaseDateTheaters	NullOr(String)	The release date of the media item in theaters.
releaseDateStreaming	NullOr(String)	The release date of the media item for streaming.
boxOfficeGross	NullOr(String)	The total box office gross revenue of the media item.
runtime	NullOr(String)	The runtime duration of the media item.
soundMix	NullOr(Array)	An array of sound mixes used in the media item.
promoEndpoint	NullOr(String)	The promo video endpoint (m3u8) for the media item.
episodes	NullOr(Array)	An array of episodes for TV shows, where each episode includes:
	- title: String	The title of the episode.
	- description: String	A brief description of the episode's plot or storyline.
	- airDate: String	The air date of the episode.
	- episodeNumber: Number	The episode number within the season.
	- seasonNumber: Number	The season number to which the episode belongs.

Get TopCritics

import { getTopCritics } from 'unofficial-rottentomatoes'

const id = 'm/harry_potter_and_the_deathly_hallows_part_2'
const row = await getTopCritics(id)

TopCritics Response Schema

The TopCriticsSchema defines the structure for top critic reviews of a specific media item. Each field provides details about a critic's review, including the critic's identity, publication, and additional context for the review.

Field	Type	Description
reviewerId	NullOr(String)	Unique identifier for the reviewer.
reviewer	NullOr(String)	Name of the reviewer.
publication	NullOr(String)	The publication that the review is associated with.
quote	NullOr(String)	A quote or excerpt from the review.
originalScore	NullOr(String)	The score or rating given by the reviewer, in its original format.
reviewDate	NullOr(String)	Date when the review was published.
reviewLink	NullOr(String)	URL link to the full review.
criticPicture	NullOr(String)	URL of the critic's picture.

Get Critic

import { getCritic } from 'unofficial-rottentomatoes'

const reviewerId = 'critics/christopher-kelly'
const criticMediaType = 'movies'

const row = await getCritic(reviewerId, mediaType)

Critic Schema

The CriticSchema defines the structure for the data returned by the getCritic function.

CriticsSchema

The CriticsSchema captures the details of a critic's profile, including their biography and individual reviews.

CriticReviewSchema

Each review provided by a critic is structured as follows:

Field	Type	Description
rating	NullOr(String)	Rating provided by the critic in text format.
tomatometerScore	NullOr(NumberFromString)	Numeric score on the tomatometer scale.
title	NullOr(String)	Title of the media reviewed.
year	NullOr(NumberFromString)	Year of the media release.
reviewSnippet	NullOr(String)	Short excerpt or summary of the review.
publication	NullOr(String)	Name of the publication where the review was published.
reviewLink	NullOr(String)	URL link to the full review.
reviewDate	NullOr(String)	Date when the review was published.

CriticBioSchema

The critic's biographical information is captured as follows:

Field	Type	Description
name	NullOr(String)	Name of the critic.
image	NullOr(String)	URL to an image of the critic.
approvalStatus	NullOr(String)	Status of the critic’s approval, if available.
publications	NullOr(Array(NullOr(String)))	List of publications the critic is associated with.
criticsGroup	NullOr(String)	Name of the critics' group or association.

Full Response Schema Structure

The CriticsSchema combines both the bio and reviews data structures:

Field	Type	Description
reviews	Array(CriticReviewSchema)	Array of individual reviews by the critic.
bio	CriticBioSchema	Biographical information of the critic.

:handshake: Contributing

• Fork it!
• Create your feature branch: git checkout -b my-new-feature
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request

---

:busts_in_silhouette: Credits

• Chris Michael (Project Leader, and Developer)

---

:anger: Troubleshootings

This is just a personal project created for study / demonstration purpose and to simplify my working life, it may or may not be a good fit for your project(s).

---

:heart: Show your support

Please :star: this repository if you like it or this project helped you!
Feel free to open issues or submit pull-requests to help me improving my work.

---

:robot: Author

Chris M. Perez

You can follow me on github · twitter

---

Copyright ©2024 Rotten tomatoes.