Sign in

v1

latestOpenAPI 3.0.12026-07-24207094.9 KB
Reports

Ranking Report

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

post/svm/reports/ranking

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

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

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": [
            "tt31868189"
          ],
          "lftv": [
            "226049"
          ]
        },
        "original": true,
        "original_platform": "Netflix"
      }
    ],
    "platforms": [
      "netflix",
      "hulu"
    ],
    "release_information": {
      "release_date_min": "2022-01-01",
      "release_date_max": "2022-12-31"
    }
  }
}