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.

🤝 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

👥 Credits

Chris Michael (Project Leader, and Developer)

💢 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).

❤️ Show your support

Please ⭐ 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.

🤖 Author

Chris M. Perez

You can follow me on github · twitter

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github/workflows		.github/workflows
.vscode		.vscode
playground		playground
src		src
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
yarn.lock		yarn.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Unofficial Rotten Tomatoes Library

Prerequisites

Installation

Using npm

Using yarn

📚 Documentation

Browse Function Documentation

Usage Example

Browse Filter Schema

Browse Response Schema

Search for Movies or TV Shows

Search Response Schema

Get Extra Content

ExtraContent Response Schema

Get TopCritics

TopCritics Response Schema

Get Critic

Critic Schema

CriticsSchema

CriticReviewSchema

CriticBioSchema

Full Response Schema Structure

🤝 Contributing

👥 Credits

💢 Troubleshootings

❤️ Show your support

🤖 Author

About

Releases 3

Packages

Languages

License

ChrisMichaelPerezSantiago/rottentomatoes

Folders and files

Latest commit

History

Repository files navigation

Unofficial Rotten Tomatoes Library

Prerequisites

Installation

Using npm

Using yarn

📚 Documentation

Browse Function Documentation

Usage Example

Browse Filter Schema

Browse Response Schema

Search for Movies or TV Shows

Search Response Schema

Get Extra Content

ExtraContent Response Schema

Get TopCritics

TopCritics Response Schema

Get Critic

Critic Schema

CriticsSchema

CriticReviewSchema

CriticBioSchema

Full Response Schema Structure

🤝 Contributing

👥 Credits

💢 Troubleshootings

❤️ Show your support

🤖 Author

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages