Reports

Ranking Report

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

post/svm/reports/ranking

Request

Base URL
https://api.luminatedata.com
URL
https://api.luminatedata.com/svm/reports/ranking
Auth
API key in header x-api-key and API key in header authorization

Request body

depthinteger required

The number of titles to return

video_type'tv_show' | 'movie' required

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

start_datestring 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_datestring 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).

genresstring[] nullable

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".

platformsstring[]

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".

ranked_by'minutes_watched' | 'views'

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

tv_show_granularity'series' | 'season' nullable

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

sourcestring[] nullable

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

country_of_originstring[] nullable

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.

original_languagestring[] nullable

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.

Example request

{
  "depth": 10,
  "video_type": "tv_show",
  "start_date": "2025-01-01",
  "end_date": "2025-01-01",
  "genres": [
    "comedy",
    "drama"
  ],
  "platforms": [
    "Netflix",
    "Hulu"
  ],
  "ranked_by": "minutes_watched",
  "source": [
    "original",
    "non-original"
  ],
  "release_information": {
    "release_date_min": "2022-01-01",
    "release_date_max": "2022-12-31"
  },
  "country_of_origin": [
    "GB",
    "KR"
  ],
  "original_language": [
    "en",
    "ko"
  ]
}

Response

Successfully retrieved ranking data

Example response

{
  "data": {
    "video_type": "movie",
    "depth": 50,
    "start_date": "2024-01-01",
    "end_date": "2024-02-01",
    "genres": [
      "action & adventure"
    ],
    "items": [
      {
        "report_rank": 1,
        "title_id": "760f8832d8a86afc6001e85bb8762404",
        "title": "Twisters",
        "season": "2",
        "genres": [
          "action & adventure",
          "thriller"
        ],
        "metrics": {
          "minutes_watched": 780821165,
          "views": 6400173,
          "duration_to_date": 123,
          "data_status": "official"
        },
        "platform_availability": [
          "Netflix",
          "HBO Max"
        ],
        "external_ids": {
          "imdb": [
            "nm0812363"
          ]
        },
        "original": true,
        "original_platform": "Netflix"
      }
    ],
    "platforms": [
      "netflix",
      "hulu"
    ],
    "country_of_origin": [
      "GB",
      "KR"
    ],
    "original_language": [
      "en",
      "ko"
    ],
    "release_information": {
      "release_date_min": "2022-01-01",
      "release_date_max": "2022-12-31"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.