Skip to content

pierrevano/whatson-api

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

What's on? API

Companion to What's on?


⚠️ This API is currently running on Render's free tier. If you'd like to keep it active at all times, please consider making a small donation here: buymeacoffee.com/pierreschelde.


IDs files available below


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