https://github.com/pierrevano/whatson-api

What's on? API
https://github.com/pierrevano/whatson-api

allocine api betaseries imdb letterboxd metacritic mojo mongodb movies nodejs rotten-tomatoes senscritique themoviesdatabase tmdb trakt tv-time tvdb tvshows whatson

Last synced: 3 months ago
JSON representation

What's on? API

Host: GitHub
URL: https://github.com/pierrevano/whatson-api
Owner: pierrevano
Created: 2022-12-27T07:47:23.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2026-03-18T23:02:27.000Z (4 months ago)
Last Synced: 2026-03-19T12:31:35.616Z (4 months ago)
Topics: allocine, api, betaseries, imdb, letterboxd, metacritic, mojo, mongodb, movies, nodejs, rotten-tomatoes, senscritique, themoviesdatabase, tmdb, trakt, tv-time, tvdb, tvshows, whatson
Language: JavaScript
Homepage: https://documenter.getpostman.com/view/18186487/2s9Ykhg4MB
Size: 26.1 MB
Stars: 28
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml

Awesome Lists containing this project

README

What's on? API

Companion to [What's on?](https://github.com/pierrevano/whatson)

---

## Usage Notice

This repository is provided under a custom non-commercial license. Non-commercial forking and modification are allowed. Commercial use is prohibited.

Use of the API and any returned data is subject to [API_TERMS.md](./API_TERMS.md). Any use of the API data remains the sole responsibility of the end user.

---

⚠️ This API is currently running on Render's free tier. If you'd like to help keep it active at all times, please consider supporting the project via GitHub Sponsors, Patreon, or Buy Me a Coffee. For any additional feedback, you can also join the Discord server: https://discord.gg/SpKw8Zg5vT.

Note: A rate limit of `1000` requests per hour is in place to prevent abuse of the API. When the limit is exceeded, the API returns a `429` response with a `Retry-After` header. An API key can be requested on demand to remove this limit by contacting me at https://pierrevano.github.io.

---

## IDs files available below

- Movies: https://whatson-assets.vercel.app/films_ids.txt
- TV Shows: https://whatson-assets.vercel.app/series_ids.txt

---

This API provides information on movies and tvshows.

## Endpoints

### **GET /**

Retrieves detailed information about either a movie or a tvshow based on the provided query parameters.

#### Default sorting behavior

By default, when no query parameters are added (or when all are used), the results are sorted according to the following criteria:

1. Sort by Popularity: The items are first sorted by their calculated average popularity rank, with lower rank values (more popular) appearing first.
2. Sort by Ratings: Among items with the same popularity, sorting is then based on their average ratings, with higher ratings appearing first.
3. Sort by Title: If items have the same popularity and ratings, they are further sorted alphabetically by their title in ascending order.

- _If you want to sort by ratings only, you must set the popularity parameter to `none`._
- _You must have at least one popularity or one rating parameter to obtain results._

To prioritise chart data, add the `top_ranking_order` or `mojo_rank_order` parameters. `top_ranking_order=asc` surfaces the lowest IMDb ranking numbers first (e.g., #1 at the top). `mojo_rank_order=asc` keeps the same behaviour on `mojo.rank`. When these parameters are present, items missing the requested metrics are filtered out. If you provide both sort options together, the precedence is `imdb.top_ranking`, then `mojo.rank`, before falling back to the default popularity, ratings, and title ordering.

#### Active items

Active items are fetched from 2 different links:

1. For movies: https://www.allocine.fr/film/aucinema/
2. For tvshows: https://www.allocine.fr/series/top/

- _These 2 links are also used to fetch the AlloCiné popularity of each item._

> ```
> https://whatson-api.onrender.com/?ratings_filters=allocine_critics,allocine_users,betaseries_users,imdb_users,metacritic_critics,metacritic_users,rottentomatoes_critics,rottentomatoes_users,letterboxd_users,senscritique_users,tmdb_users,trakt_users,tvtime_users&popularity_filters=allocine_popularity,imdb_popularity,tmdb_popularity&item_type=movie,tvshow&is_active=true,false&is_adult=true,false&must_see=true,false&users_certified=true,false&critics_certified=true,false&minimum_ratings=0,1,2,2.5,3,3.5,4,4.5&release_date=everything,new&seasons_number=1,2,3,4,5&status=canceled,ended,ongoing,pilot,unknown&directors=&genres=&platforms=&networks=&production_companies=&append_to_response=critics_rating_details,directors,episodes_details,genres,highest_episode,last_episode,lowest_episode,networks,next_episode,platforms_links,production_companies,certification_variants,image_variants,title_variants,parents_guide&filtered_seasons=&runtime=&top_ranking_order=asc,desc&mojo_rank_order=asc,desc&page=&limit=
> ```

| Parameter | Value | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| ratings_filters | allocine_critics,allocine_users,betaseries_users,imdb_users,metacritic_critics,metacritic_users,rottentomatoes_critics,rottentomatoes_users,letterboxd_users,senscritique_users,tmdb_users,trakt_users,tvtime_users | Ratings filters source (or _all_ for every values) |
| popularity_filters | allocine_popularity,imdb_popularity,tmdb_popularity | Popularity filters source (use _all_ for all values, _none_ to disable) |
| item_type | movie,tvshow | The type of the item (_movie_, _tvshow_ or both) |
| is_active | true,false | Is the item currently on screens (_true_, _false_ or both) |
| is_adult | true,false | Is the item marked as adult content (_true_, _false_ or both) |
| must_see | true,false | Is the item a Metacritic must see (_true_, _false_ or both) |
| users_certified | true,false | Has the item received the Rotten Tomatoes "Verified Audience" certification (_true_, _false_ or both) |
| critics_certified | true,false | Has the item received the Rotten Tomatoes "Certified Fresh" status from critics (_true_, _false_ or both) |
| minimum_ratings | 0,1,2,2.5,3,3.5,4,4.5 | Minimum ratings to return |
| release_date | everything,new,from:yyyy-mm-dd,to:yyyy-mm-dd | Use `new` for recent items or `from:`/`to:` with `yyyy-mm-dd` to set an inclusive date range |
| runtime | 1800,5400 | Filter items by runtime in seconds (one value for exact match or two values for an inclusive range) |
| seasons_number | 1,2,3,4,5 | Number of seasons (5 means 5+) (only valid for tvshows) |
| status | canceled,ended,ongoing,pilot,unknown | TV show's status (only valid for tvshows) |
| directors | _string_ | TV show's directors (only valid for tvshows; or `all` for every value) |
| genres | _string_ | TV show's genres (only valid for tvshows; or `all` for every value) |
| platforms | _string_ | TV show's platforms links (only valid for tvshows; or `all` for every value) |
| networks | _string_ | TV show's networks (only valid for tvshows; or `all` for every value) |
| production_companies | _string_ | TV show's production companies (only valid for tvshows; or `all` for every value) |
| append_to_response | critics_rating_details,directors,episodes_details,genres,highest_episode,last_episode,lowest_episode,networks,next_episode,platforms_links,production_companies,certification_variants,image_variants,title_variants,parents_guide | Should we return specific keys in the response |
| filtered_seasons | _string_ | Filter episodes by one or more seasons |
| top_ranking_order | asc,desc | Sort by IMDb top ranking (`asc` shows #1 first, `desc` shows #1 last; only ranked items) |
| mojo_rank_order | asc,desc | Sort by Box Office Mojo rank (`asc` shows #1 first, `desc` shows #1 last; only ranked items) |
| page | _integer_ | Page number |
| limit | _integer_ | Page items limit |

_For directors, genres, platforms, networks, and production companies, you can use the `^` and `$` regex delimiters to perform strict matching._

`certification_variants`, `image_variants`, and `title_variants` are append-only fields and currently expose only a French (`fr`) localized variant. If you need another locale, contact me at https://pierrevano.github.io.

### Search

The query parameters provided below are solely for item search purposes and must be unique.

> ```
> https://whatson-api.onrender.com/?title=&append_to_response=critics_rating_details,directors,episodes_details,genres,highest_episode,last_episode,lowest_episode,networks,next_episode,platforms_links,production_companies,certification_variants,image_variants,title_variants,parents_guide&filtered_seasons=
> ```

| Parameter | Value | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| title | _string_ | Title of the movie or tvshow (also matches `original_title` and localized `title_variants`) |
| allocineId | _integer_ | AlloCiné ID of the movie or tvshow |
| betaseriesId | _string_ | BetaSeries ID of the movie or tvshow |
| imdbId | _string_ | IMDb ID of the movie or tvshow |
| letterboxdId | _string_ | Letterboxd ID of the movie |
| metacriticId | _string_ | Metacritic ID of the movie or tvshow |
| rottentomatoesId | _string_ | Rotten Tomatoes ID of the movie or tvshow |
| senscritiqueId | _integer_ | SensCritique ID of the movie or tvshow |
| tmdbId | _integer_ | The Movie Database ID of the movie or tvshow |
| traktId | _string_ or _integer_ | Trakt ID of the movie or tvshow |
| tvtimeId | _integer_ | TV Time ID of the tvshow |
| thetvdbId | _integer_ | TheTVDB ID of the movie or tvshow |
| append_to_response | critics_rating_details,directors,episodes_details,genres,highest_episode,last_episode,lowest_episode,networks,next_episode,platforms_links,production_companies,certification_variants,image_variants,title_variants,parents_guide | Should we return specific keys in the response |
| filtered_seasons | _string_ | Filter episodes by one or more seasons |

#### Responses:

- `200` A successful response
- `400` Invalid query parameters were passed
- `404` No items have been found (or invalid endpoint)
- `405` Method not allowed
- `429` Too many requests (rate limit exceeded)
- `500` Internal server error

---

### **GET /episodes/rated**

Returns the highest or lowest rated episodes across all tvshows combined.

You can also see it live at https://whatson-top-episodes.vercel.app.

> ```
> https://whatson-api.onrender.com/episodes/rated?order=asc,desc&is_active=true,false&is_adult=true,false&must_see=true,false&users_certified=true,false&critics_certified=true,false&minimum_ratings=&minimum_users_rating_count=&release_date=from:,to:&filtered_seasons=&directors=&genres=&platforms=&networks=&production_companies=&status=canceled,ended,ongoing,pilot,unknown&title=&page=&limit=
> ```

| Parameter | Value | Description |
| -------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| order | asc,desc | `desc` returns top rated episodes, `asc` returns lowest rated episodes |
| is_active | true,false | Is the tvshow currently active (`true`, `false` or both) |
| is_adult | true,false | Is the tvshow marked as adult content (`true`, `false` or both) |
| must_see | true,false | Is the tvshow a Metacritic must see (`true`, `false` or both) |
| users_certified | true,false | Has the tvshow received Rotten Tomatoes user certification |
| critics_certified | true,false | Has the tvshow received Rotten Tomatoes critics certification |
| minimum_ratings | _number_ | Minimum IMDb users rating to return on episodes |
| minimum_users_rating_count | _number_ | Minimum number of IMDb users ratings required for each episode. Defaults to `100` when omitted |
| release_date | from:yyyy-mm-dd,to:yyyy-mm-dd | Use `from:`/`to:` with `yyyy-mm-dd` to set an inclusive date range |
| filtered_seasons | _string_ | Filter episodes by one or more seasons |
| directors | _string_ | Filter tvshows by directors, or use `all` for every value |
| genres | _string_ | Filter tvshows by genres, or use `all` for every value |
| platforms | _string_ | Filter tvshows by streaming platforms, or use `all` for every value |
| networks | _string_ | Filter tvshows by networks, or use `all` for every value |
| production_companies | _string_ | Filter tvshows by production companies, or use `all` for every value |
| status | canceled,ended,ongoing,pilot,unknown | Filter tvshows by status |
| title | _string_ | Search across the tvshow title, episode title, or tvshow networks |
| page | _integer_ | Requested page number |
| limit | _integer_ | Number of rated episodes to return |

#### Responses:

Example of a rated episodes response returned:

```jsonc
{
"page": "number",
"results": [
{
"tvshow": {
"id": "number", // The Movie Database ID of the tvshow
"item_type": "string", // Type of the item (e.g. tvshow)
"title": "string", // Title of the tvshow
"image": "string", // Image of the tvshow
"networks": "object", // Networks attached to the tvshow
"seasons_number": "number", // Number of seasons available on the tvshow
"status": "string", // Status of the tvshow
},
"season": "number", // Season number of the episode
"episode": "number", // Episode number within the season
"title": "string", // Title of the episode
"description": "string", // Description of the episode
"id": "string", // IMDb specific identifier
"url": "string", // URL to the IMDb page
"release_date": "string", // Release date of the episode
"users_rating": "number", // Average rating given by IMDb users
"users_rating_count": "number", // Total number of ratings submitted by IMDb users
},
],
"total_pages": "number",
"total_results": "number",
}
```

---

### **GET /{item_type}/{id}**

Provides detailed information about a specific item (movie or tvshow) by its type and unique identifier (TMDB ID).

> ```
> https://whatson-api.onrender.com/{item_type}/:id?ratings_filters=allocine_critics,allocine_users,betaseries_users,imdb_users,metacritic_critics,metacritic_users,rottentomatoes_critics,rottentomatoes_users,letterboxd_users,senscritique_users,tmdb_users,trakt_users,tvtime_users&append_to_response=critics_rating_details,directors,episodes_details,genres,highest_episode,last_episode,lowest_episode,networks,next_episode,platforms_links,production_companies,certification_variants,image_variants,title_variants,parents_guide
> ```

#### Responses:

---

Example of an item returned:

```jsonc
{
"_id": "string", // Unique MongoDB identifier for the item

"id": "number", // General identifier (The Movie Database ID)
"item_type": "string", // Type of the item (e.g., movie or tvshow)
"is_active": "boolean", // Indicates if the item is currently active
"title": "string", // Title of the item
/*
* To include this key in the response, add `title_variants` to the `append_to_response` query parameter.
*/
"title_variants": {
"fr": "string", // French title variant
},
"original_title": "string", // Original title of the item

/*
* To include this key in the response, add `directors` to the `append_to_response` query parameter.
*/
"directors": "object", // Directors' names
/*
* To include this key in the response, add `genres` to the `append_to_response` query parameter.
*/
"genres": "object", // Genres' names
"image": "string", // URL to the item's image
/*
* To include this key in the response, add `image_variants` to the `append_to_response` query parameter.
*/
"image_variants": {
"fr": "string", // French image variant
},
"is_adult": "boolean", // Indicates if the title is flagged as adult content on IMDb
"certification": "string", // US age classification assigned by IMDb (e.g., G, PG-13, R)
/*
* To include this key in the response, add `certification_variants` to the `append_to_response` query parameter.
*/
"certification_variants": {
"fr": "string", // French certification variant
},
/*
* To include this key in the response, add `parents_guide` to the `append_to_response` query parameter.
*/
"parents_guide": {
"url": "string",
"categories": [
{
"title": "string",
"severity": "string",
},
],
},
/*
* To include this key in the response, add `networks` to the `append_to_response` query parameter.
*/
"networks": "object", // Networks' names
/*
* To include this key in the response, add `platforms_links` to the `append_to_response` query parameter.
*/
"platforms_links": [
{
"name": "string", // Name of the streaming platform
"link_url": "string", // URL to the streaming platform
},
],
/*
* To include this key in the response, add `production_companies` to the `append_to_response` query parameter.
*/
"production_companies": "object", // Production Companies' names
"release_date": "string", // Release date of the item
"runtime": "number", // Runtime duration expressed in seconds
"tagline": "string", // Tagline of the item
"trailer": "string", // URL to the item's trailer

"episodes_details": [
/*
* To include this key in the response, add `episodes_details` to the `append_to_response` query parameter.
* To filter episodes by one or more seasons, add the `filtered_seasons` query parameter with the desired seasons numbers.
*/
{
"season": "number", // Season number of the episode
"episode": "number", // Episode number within the season
"title": "string", // Title of the episode
"description": "string", // Description of the episode
"id": "string", // IMDb specific identifier
"url": "string", // URL to the IMDb page
"release_date": "string", // Release date of the episode
"users_rating": "number", // Average rating given by IMDb users
"users_rating_count": "number", // Total number of ratings submitted by IMDb users
},
],
/*
* To include this key in the response, add `last_episode` to the `append_to_response` query parameter.
*/
"last_episode": {
/* Information related to the most recent episode */
"season": "number", // Season number of the most recent episode
"episode": "number", // Episode number for the most recent episode
"episode_type": "string", // Type of the most recent episode
"title": "string", // Title of the most recent episode
"description": "string", // Description of the most recent episode
"id": "string", // IMDb specific identifier for the most recent episode
"url": "string", // URL to the IMDb page of the most recent episode
"release_date": "string", // Release date of the most recent episode
"users_rating": "number", // Average rating given by IMDb users for the most recent episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the most recent episode
},
/*
* To include this key in the response, add `next_episode` to the `append_to_response` query parameter.
*/
"next_episode": {
/* Information related to the next episode to air */
"season": "number", // Season number of the next episode to air
"episode": "number", // Episode number for the next episode to air
"episode_type": "string", // Type of the next episode to air
"title": "string", // Title of the next episode to air
"description": "string", // Description of the next episode to air
"id": "string", // IMDb specific identifier for the next episode to air
"url": "string", // URL to the IMDb page of the next episode to air
"release_date": "string", // Release date of the next episode to air
"users_rating": "number", // Average rating given by IMDb users for the next episode to air
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the next episode to air
},
/*
* To include this key in the response, add `highest_episode` to the `append_to_response` query parameter.
*/
"highest_episode": {
/* Highest rated episode across all seasons */
"season": "number", // Season number of the highest-rated episode
"episode": "number", // Episode number of the highest-rated episode
"title": "string", // Title of the highest-rated episode
"description": "string", // Description of the highest-rated episode
"id": "string", // IMDb specific identifier for the highest-rated episode
"url": "string", // URL to the IMDb page of the highest-rated episode
"release_date": "string", // Release date of the highest-rated episode
"users_rating": "number", // Average rating given by IMDb users for the highest-rated episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the highest-rated episode
},
/*
* To include this key in the response, add `lowest_episode` to the `append_to_response` query parameter.
*/
"lowest_episode": {
/* Lowest rated episode across all seasons */
"season": "number", // Season number of the lowest-rated episode
"episode": "number", // Episode number of the lowest-rated episode
"title": "string", // Title of the lowest-rated episode
"description": "string", // Description of the lowest-rated episode
"id": "string", // IMDb specific identifier for the lowest-rated episode
"url": "string", // URL to the IMDb page of the lowest-rated episode
"release_date": "string", // Release date of the lowest-rated episode
"users_rating": "number", // Average rating given by IMDb users for the lowest-rated episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the lowest-rated episode
},
"seasons_number": "number", // Number of seasons available
"status": "string", // Current status of the item (e.g., ongoing, ended, etc.)

"allocine": {
/* Information related to AlloCiné platform */
"id": "number", // AlloCiné specific identifier
"url": "string", // URL to the AlloCiné page
"users_rating": "number", // Average rating given by AlloCiné users
"users_rating_count": "number", // Total number of ratings submitted by AlloCiné users
"critics_rating": "number", // Average rating given by AlloCiné critics
"critics_rating_count": "number", // Total number of ratings submitted by AlloCiné critics
"critics_rating_details": [
// To display this key, add `critics_rating_details` to the query parameter `append_to_response`
{
"critic_name": "string", // Name of the critic
"critic_rating": "number", // Average rating given by the critic
},
],
"popularity": "number", // Popularity score on AlloCiné
},
"betaseries": {
/* Information related to BetaSeries platform */
"id": "string", // BetaSeries specific identifier
"url": "string", // URL to the BetaSeries page
"users_rating": "number", // Average rating given by BetaSeries users
"users_rating_count": "number", // Total number of ratings submitted by BetaSeries users
},
"imdb": {
/* Information related to IMDb platform */
"id": "string", // IMDb specific identifier
"url": "string", // URL to the IMDb page
"users_rating": "number", // Average rating given by IMDb users
"users_rating_count": "number", // Total number of ratings submitted by IMDb users
"popularity": "number", // Popularity score on IMDb
"top_ranking": "number", // Position of the title in IMDb top charts
},
"letterboxd": {
/* Information related to Letterboxd platform */
"id": "string", // Letterboxd specific identifier
"url": "string", // URL to the Letterboxd page
"users_rating": "number", // Average rating given by Letterboxd users
"users_rating_count": "number", // Total number of ratings submitted by Letterboxd users
},
"metacritic": {
/* Information related to Metacritic platform */
"id": "string", // Metacritic specific identifier
"url": "string", // URL to the Metacritic page
"users_rating": "number", // Average rating given by Metacritic users
"users_rating_count": "number", // Total number of ratings submitted by Metacritic users
"critics_rating": "number", // Average rating given by Metacritic critics
"critics_rating_count": "number", // Total number of ratings submitted by Metacritic critics
"must_see": "boolean", // Whether the title has received the "Must-See" badge on Metacritic
},
"rotten_tomatoes": {
/* Information related to Rotten Tomatoes platform */
"id": "string", // Rotten Tomatoes specific identifier
"url": "string", // URL to the Rotten Tomatoes page
"users_rating": "number", // Average rating given by Rotten Tomatoes users
"users_rating_count": "number", // Total number of ratings submitted by Rotten Tomatoes users (calculated as liked + not liked votes)
"users_rating_liked_count": "number", // Total number of liked ratings submitted by Rotten Tomatoes users
"users_rating_not_liked_count": "number", // Total number of not liked ratings submitted by Rotten Tomatoes users
"users_certified": "boolean", // Has the item received the Rotten Tomatoes "Verified Audience" certification
"critics_rating": "number", // Average rating given by Rotten Tomatoes critics
"critics_rating_count": "number", // Total number of ratings submitted by Rotten Tomatoes critics
"critics_rating_liked_count": "number", // Total number of liked ratings submitted by Rotten Tomatoes critics
"critics_rating_not_liked_count": "number", // Total number of not liked ratings submitted by Rotten Tomatoes critics
"critics_certified": "boolean", // Has the item received the Rotten Tomatoes "Certified Fresh" status from critics
},
"senscritique": {
/* Information related to SensCritique platform */
"id": "number", // SensCritique specific identifier
"url": "string", // URL to the SensCritique page
"users_rating": "number", // Average rating given by SensCritique users
"users_rating_count": "number", // Total number of ratings submitted by SensCritique users
},
"tmdb": {
/* Information related to The Movie Database (TMDB) platform */
"id": "number", // TMDB specific identifier
"url": "string", // URL to the TMDB page
"users_rating": "number", // Average rating given by TMDB users
"users_rating_count": "number", // Total number of ratings submitted by TMDB users
"popularity": "number", // Popularity score on TMDB
},
"trakt": {
/* Information related to Trakt platform */
"id": ["string", "number"], // Trakt specific identifier
"url": "string", // URL to the Trakt page
"users_rating": "number", // Average rating given by Trakt users
"users_rating_count": "number", // Total number of ratings submitted by Trakt users
},
"tv_time": {
/* Information related to TV Time platform */
"id": "number", // TV Time specific identifier
"url": "string", // URL to the TV Time page
"users_rating": "number", // Average rating given by TV Time users
},
"thetvdb": {
/* Information related to TheTVDB platform */
"id": "number", // TheTVDB specific identifier
"slug": "string", // Slug for the identifier on TheTVDB
"url": "string", // URL to TheTVDB page
},

"mojo": {
/* Information related to Box Office Mojo platform */
"rank": "number", // Ranking according to Box Office Mojo
"url": "string", // URL to the Box Office Mojo page
"lifetime_gross": "number", // Lifetime gross revenue in US dollars
},

"updated_at": "string", // Timestamp of the last update

"popularity_average": "number", // Average popularity score across platforms (AlloCiné, IMDb, and TMDB)
"ratings_average": "number", // Average rating score across platforms (all)
}
```

---

### **GET /tvshow/{id}/seasons**

Returns season-level metadata for a tvshow.

> ```
> https://whatson-api.onrender.com/tvshow/:id/seasons?append_to_response=highest_episode,last_episode,lowest_episode,next_episode,rating_distribution,rating_distribution_episodes
> ```

| Parameter | Value | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| append_to_response | highest_episode,last_episode,lowest_episode,next_episode,rating_distribution,rating_distribution_episodes (comma-separated) | Should we return specific keys in the response |

#### Responses:

- `200` A successful response
- `404` No items have been found (or invalid endpoint)
- `405` Method not allowed
- `429` Too many requests (rate limit exceeded)
- `500` Internal server error

---

### **GET /tvshow/{id}/seasons/{season_number}/episodes**

Returns the list of episodes for a specific season, with optional episode-level filters.

> ```
> https://whatson-api.onrender.com/tvshow/:id/seasons/:season_number/episodes?minimum_ratings=&release_date=from:,to:
> ```

| Parameter | Value | Description |
| --------------- | ----------------------------- | ------------------------------------------------------------------ |
| minimum_ratings | _number_ | Minimum ratings to return |
| release_date | from:yyyy-mm-dd,to:yyyy-mm-dd | Use `from:`/`to:` with `yyyy-mm-dd` to set an inclusive date range |

#### Responses:

- `200` A successful response
- `404` No items have been found (or invalid endpoint)
- `405` Method not allowed
- `429` Too many requests (rate limit exceeded)
- `500` Internal server error

---

### **GET /tvshow/{id}/seasons/{season_number}/episodes/{episode_number}**

Returns details for a specific episode inside a specific season.

> ```
> https://whatson-api.onrender.com/tvshow/:id/seasons/:season_number/episodes/:episode_number
> ```

#### Responses:

- `200` A successful response
- `404` No items have been found (or invalid endpoint)
- `405` Method not allowed
- `429` Too many requests (rate limit exceeded)
- `500` Internal server error

---

Example of a specific tvshow response returned on season-level endpoints:

```jsonc
{
"id": "number", // General identifier (The Movie Database ID)
"item_type": "string", // Type of the item (e.g., tvshow)
"title": "string", // Title of the item
"image": "string", // Image of the tvshow
"networks": "object", // Networks attached to the tvshow
"seasons_number": "number", // Number of seasons available on the tvshow
"status": "string", // Status of the tvshow

/*
* Returned on `/tvshow/{id}/seasons`.
*/
"seasons": [
{
"season_number": "number", // Season number of the episode
"episodes_count": "number", // Number of episodes available in the season
"average_users_rating": "number", // Average rating given by IMDb users
"users_rating_count": "number", // Total number of ratings submitted by IMDb users
"highest_episode": {
"season": "number", // Season number of the highest-rated episode
"episode": "number", // Episode number of the highest-rated episode
"title": "string", // Title of the highest-rated episode
"description": "string", // Description of the highest-rated episode
"id": "string", // IMDb specific identifier for the highest-rated episode
"url": "string", // URL to the IMDb page of the highest-rated episode
"release_date": "string", // Release date of the highest-rated episode
"users_rating": "number", // Average rating given by IMDb users for the highest-rated episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the highest-rated episode
},
"lowest_episode": {
"season": "number", // Season number of the lowest-rated episode
"episode": "number", // Episode number of the lowest-rated episode
"title": "string", // Title of the lowest-rated episode
"description": "string", // Description of the lowest-rated episode
"id": "string", // IMDb specific identifier for the lowest-rated episode
"url": "string", // URL to the IMDb page of the lowest-rated episode
"release_date": "string", // Release date of the lowest-rated episode
"users_rating": "number", // Average rating given by IMDb users for the lowest-rated episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the lowest-rated episode
},
/*
* Returned on `/tvshow/{id}/seasons` when
* `append_to_response` includes `rating_distribution`.
*/
"rating_distribution": {
"[1-10]": "number", // Rating bucket (1-10, rounded users rating) mapped to episode count; only returned when count > 0
},
/*
* Returned on `/tvshow/{id}/seasons` when
* `append_to_response` includes `rating_distribution_episodes`.
*/
"rating_distribution_episodes": {
"[1-10]": [
{
"season": "number", // Season number of the episode
"episode": "number", // Episode number within the season
"title": "string", // Title of the episode
"description": "string", // Description of the episode
"id": "string", // IMDb specific identifier
"url": "string", // URL to the IMDb page
"release_date": "string", // Release date of the episode
"users_rating": "number", // Average rating given by IMDb users
"users_rating_count": "number", // Total number of ratings submitted by IMDb users
},
], // Episodes for the corresponding rating bucket key (1-10)
},
},
],

/*
* Returned on `/tvshow/{id}/seasons/{season_number}/episodes`.
*/
"season_number": "number", // Season number of the episode
"total_episodes": "number", // Number of episodes returned in the season
"episodes": [
{
"season": "number", // Season number of the episode
"episode": "number", // Episode number within the season
"title": "string", // Title of the episode
"description": "string", // Description of the episode
"id": "string", // IMDb specific identifier
"url": "string", // URL to the IMDb page
"release_date": "string", // Release date of the episode
"users_rating": "number", // Average rating given by IMDb users
"users_rating_count": "number", // Total number of ratings submitted by IMDb users
},
],

/*
* Returned on `/tvshow/{id}/seasons/{season_number}/episodes/{episode_number}`.
*/
"episode_number": "number", // Episode number within the season
"episode": {
"season": "number", // Season number of the episode
"episode": "number", // Episode number within the season
"title": "string", // Title of the episode
"description": "string", // Description of the episode
"id": "string", // IMDb specific identifier
"url": "string", // URL to the IMDb page
"release_date": "string", // Release date of the episode
"users_rating": "number", // Average rating given by IMDb users
"users_rating_count": "number", // Total number of ratings submitted by IMDb users
},

/*
* Returned on `/tvshow/{id}/seasons` when
* `append_to_response` includes `highest_episode`.
*/
"highest_episode": {
"season": "number", // Season number of the highest-rated episode
"episode": "number", // Episode number of the highest-rated episode
"title": "string", // Title of the highest-rated episode
"description": "string", // Description of the highest-rated episode
"id": "string", // IMDb specific identifier for the highest-rated episode
"url": "string", // URL to the IMDb page of the highest-rated episode
"release_date": "string", // Release date of the highest-rated episode
"users_rating": "number", // Average rating given by IMDb users for the highest-rated episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the highest-rated episode
},
/*
* Returned on `/tvshow/{id}/seasons` when
* `append_to_response` includes `last_episode`.
*/
"last_episode": {
"season": "number", // Season number of the most recent episode
"episode": "number", // Episode number for the most recent episode
"episode_type": "string", // Type of the most recent episode
"title": "string", // Title of the most recent episode
"description": "string", // Description of the most recent episode
"id": "string", // IMDb specific identifier for the most recent episode
"url": "string", // URL to the IMDb page of the most recent episode
"release_date": "string", // Release date of the most recent episode
"users_rating": "number", // Average rating given by IMDb users for the most recent episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the most recent episode
},
/*
* Returned on `/tvshow/{id}/seasons` when
* `append_to_response` includes `lowest_episode`.
*/
"lowest_episode": {
"season": "number", // Season number of the lowest-rated episode
"episode": "number", // Episode number of the lowest-rated episode
"title": "string", // Title of the lowest-rated episode
"description": "string", // Description of the lowest-rated episode
"id": "string", // IMDb specific identifier for the lowest-rated episode
"url": "string", // URL to the IMDb page of the lowest-rated episode
"release_date": "string", // Release date of the lowest-rated episode
"users_rating": "number", // Average rating given by IMDb users for the lowest-rated episode
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the lowest-rated episode
},
/*
* Returned on `/tvshow/{id}/seasons` when
* `append_to_response` includes `next_episode`.
*/
"next_episode": {
"season": "number", // Season number of the next episode to air
"episode": "number", // Episode number for the next episode to air
"episode_type": "string", // Type of the next episode to air
"title": "string", // Title of the next episode to air
"description": "string", // Description of the next episode to air
"id": "string", // IMDb specific identifier for the next episode to air
"url": "string", // URL to the IMDb page of the next episode to air
"release_date": "string", // Release date of the next episode to air
"users_rating": "number", // Average rating given by IMDb users for the next episode to air
"users_rating_count": "number", // Total number of ratings submitted by IMDb users for the next episode to air
},
}
```

---

Postman collection: https://documenter.getpostman.com/view/18186487/2s9Ykhg4MB

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/pierrevano/whatson-api

Awesome Lists containing this project

README

What's on? API