Companion to What's on?
- 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.
Retrieves detailed information about either a movie or a tvshow based on the provided query parameters.
By default, when no query parameters are added (or when all are used), the results are sorted according to the following criteria:
- Sort by Popularity: The items are first sorted by their calculated average popularity, with higher popularity values appearing first.
- Sort by Ratings: Among items with the same popularity, sorting is then based on their average ratings, with higher ratings appearing first.
- 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 are fetched from 2 different links:
- For movies: https://www.allocine.fr/film/aucinema
- 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 |
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 |
200
A successful response404
No items have been found500
Internal server error
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 |
200
A successful response404
No items have been found500
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