Ranking Report

post

https://api.luminatedata.com/svm/reports/ranking

Retrieves a list of most-watched titles within custom parameters.

Body Params

Ranking report request body

depth

int32

required

1 to 200

The number of titles to return

video_type

string

enum

required

Type of video content, either ‘movie' or 'tv_show'

Allowed:

start_date

date

required

First date used in the aggregation of the consumption data. Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).

end_date

date

required

Last date used in the aggregation of the consumption data. Value must be formatted according to the ISO 8601 date standard (YYYY-MM-DD).

genres

array of strings | null

Optional list of genres to filter results by. If not provided, all genres are included. Valid values: "action & adventure", "animation", "comedy", "crime", "documentary", "drama", "family", "fantasy", "horror", "kids", "musical", "mystery", "romance", "science fiction", "thriller", "western".

genres

platforms

array of strings

Filter results by one or more platforms. If not provided, all platforms are included. Valid values: "AMC+", "Apple TV", "BritBox", "Discovery+", "Disney+", "HBO Max", "Hulu", "Netflix", "Paramount+", "Peacock", "Prime Video", "Tubi".

platforms

ranked_by

string

enum

Defaults to minutes_watched

Metric to rank results by. Default is 'minutes_watched', alternative is 'views'.

Allowed:

tv_show_granularity

string | null

enum

Defaults to season

Optional field to distinguish between TV shows and series. 'season' is default.

Allowed:

source

array of strings | null

Optional list to filter results by content source. If not provided, both original and non-original content are included. Valid values: "original", "non-original".

source

release_information

object | null

Optional release date range filter. If provided, results are filtered to titles released within the specified date range (inclusive).

country_of_origin

array of strings | null

Optional list of countries of origin to filter results by, as case-insensitive ISO 3166-1 alpha-2 codes. If not provided, all countries are included. Titles with any of the given countries of origin are returned. Only supported for movie and tv_show season reports; rejected when tv_show_granularity is series.

country_of_origin

original_language

array of strings | null

Optional list of original languages to filter results by, as two-letter ISO 639-1 language codes (e.g., ['en', 'fr']); matching is case-insensitive. Languages without a two-letter code use a three-letter ISO 639-2/639-3 code (e.g., 'yue' for Cantonese, 'zxx' for no dialogue). If not provided, all languages are included. Titles with any of the given original languages are returned. Only supported for movie and tv_show season reports; rejected when tv_show_granularity is series.

original_language

Responses

200Successfully retrieved ranking data

400Invalid request parameters