What's on? API

Companion to What's on?

---

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, with higher popularity values 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.

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/?popularity_filters=allocine_popularity,imdb_popularity&ratings_filters=allocine_critics,allocine_users,betaseries_users,imdb_users,metacritic_critics,metacritic_users,rottenTomatoes_critics,rottenTomatoes_users,senscritique_users,tmdb_users,trakt_users&item_type=movie,tvshow&minimum_ratings=0,1,2,2.5,3,3.5,4,4.5&seasons_number=1,2,3,4,5&status=canceled,ended,ongoing,pilot,unknown&is_active=true,false&critics_rating_details=<boolean>&episodes_details=<boolean>&page=<integer>&limit=<integer>

Parameter	Value	Description
popularity_filters	allocine_popularity,imdb_popularity	Popularity filters source (or none to disable it)
ratings_filters	allocine_critics,allocine_users,betaseries_users,imdb_users,metacritic_critics,metacritic_users,rottenTomatoes_critics,rottenTomatoes_users,senscritique_users,tmdb_users,trakt_users	Ratings filters source (or all for every values)
item_type	movie,tvshow	The type of the item (movie, tvshow or both)
minimum_ratings	0,1,2,2.5,3,3.5,4,4.5	Minimum ratings to return
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)
is_active	true,false	Is the item currently on screens (true, false or both)
critics_rating_details	boolean	Should we return critics_rating_details in the response
episodes_details	boolean	Should we return episodes_details in the response
page	integer	Page number
limit	integer	Page items limit

Search

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

https://whatson-api.onrender.com/?title=<string>

Parameter	Value	Description
title	string	Title of the movie or tvshow
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	Trakt ID of the movie or tvshow

Responses:

• 200 A successful response
• 404 No items have been found
• 500 Internal server error

---

GET /{item_type}/{id}

Provides detailed information about 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,senscritique_users,tmdb_users,trakt_users&critics_rating_details=<boolean>&episodes_details=<boolean>

Parameter	Value	Description
ratings_filters	allocine_critics,allocine_users,betaseries_users,imdb_users,metacritic_critics,metacritic_users,rottenTomatoes_critics,rottenTomatoes_users,senscritique_users,tmdb_users,trakt_users	Ratings filters source
critics_rating_details	boolean	Should we return critics_rating_details in the response
episodes_details	boolean	Should we return episodes_details in the response

Responses:

• 200 A successful response
• 404 No items have been found
• 500 Internal server error

---

Example of an item returned:

{
  "_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

  "directors": "object", // Directors' names
  "genres": "object", // Genres' names
  "image": "string", // URL to the item's image
  "release_date": "string", // Release date of the item
  "tagline": "string", // Tagline of the item
  "trailer": "string", // URL to the item's trailer

  "episodes_details": [
    // To display this key, add the query parameter `episodes_details=true`
    {
      "season": "number", // Season number of the episode
      "episode": "number", // Episode number within the season
      "title": "string", // Title of the episode
      "id": "string", // IMDb specific identifier
      "url": "string", // URL to the IMDb page
      "users_rating": "number" // Rating given by IMDb users
    }
  ],
  "platforms_links": [
    {
      "name": "string", // Name of the streaming platform
      "link_url": "string" // URL to the streaming platform
    }
  ],
  "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", // Rating given by AlloCiné users
    "critics_rating": "number", // Rating given by AlloCiné critics
    "critics_number": "number", // Number of AlloCiné critics who rated
    "critics_rating_details": [
      // To display this key, add the query parameter `critics_rating_details=true`
      {
        "critic_name": "string", // Name of the critic
        "critic_rating": "number" // 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" // Rating given by BetaSeries users
  },
  "imdb": {
    /* Information related to IMDb platform */
    "id": "string", // IMDb specific identifier
    "url": "string", // URL to the IMDb page
    "users_rating": "number", // Rating given by IMDb users
    "popularity": "number" // Popularity score on IMDb
  },
  "letterboxd": {
    /* Information related to Letterboxd platform */
    "id": "string", // Letterboxd specific identifier
    "url": "string", // URL to the Letterboxd page
    "users_rating": "number" // Rating given by Letterboxd users
  },
  "metacritic": {
    /* Information related to Metacritic platform */
    "id": "string", // Metacritic specific identifier
    "url": "string", // URL to the Metacritic page
    "users_rating": "number", // Rating given by Metacritic users
    "critics_rating": "number" // Rating given by Metacritic critics
  },
  "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", // Rating given by Rotten Tomatoes users
    "critics_rating": "number" // Rating given by Rotten Tomatoes critics
  },
  "senscritique": {
    /* Information related to SensCritique platform */
    "id": "number", // SensCritique specific identifier
    "url": "string", // URL to the SensCritique page
    "users_rating": "number" // Rating given 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" // Rating given by TMDB users
  },
  "trakt": {
    /* Information related to Trakt platform */
    "id": "string", // Trakt specific identifier
    "url": "string", // URL to the Trakt page
    "users_rating": "number" // Rating given by Trakt users
  },

  "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": "string" // Lifetime gross revenue (formatted as string with $)
  },

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

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

---

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