Video Popularity

Gracenote Video Popularity assigns a numeric score to TV series and movies that represents the majority of the population's level of recognition of a video program.

The score is based on a proprietary algorithm applied across a combination of Gracenote and Nielsen data sources to ensure a high-quality and consistent metadata product. The scores are optimized for program search, discovery, and editorial curation use cases.

Program Types and Coverage

Popularity scores are calculated at the Root Id level for a program. All programs that are associated with the same Root Id will have the same popularity score.

Gracenote US Video Popularity covers the following programs:

Programs that have aired in the United States
Released TV series at the series level
Released Movies

Gracenote US Video Popularity does not cover the following programs:

Sports programming (e.g. specific sports games)
One-time specials (e.g. the Oscars)
Local news programming
Episode-level popularity

Getting Seed Data and Updates

To download the entire endpoint, and to update it on a daily basis, follow the steps described here: Getting Seed Files and Getting Updates.

Video Popularity scores for all programs are updated daily. You should check for updates regularly to ensure you are using the latest scores.

Request Parameters

Parameter	Required?	Description
api_key	Yes	24-character key obtained during application registration
updateId	No	Video popularities modified at or after `updateId`.
limit	No	Batch size. Maximum number of video popularities to be returned. Use with `updateId`.
tmsId	No	For non-batch lookups. 14-char tmsId format. Accepts comma-separated list of IDs. Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

Response Body

The table below shows parameters that may be included in Video Popularity response.

Attribute	Description
tmsId	The TMS ID of a program
score	Numeric Video Popularity score value.
score_date	Date of the score.

Below is an example response. You can also use the API Explorer described in Using the On API to test these APIs and view sample responses.

The full response format is specified in the schema file: http://files.api.gracenote.com/xsd/on_update_videoPopularities_3.20.xsd.For an interactive HTML version of the schemas, refer to Schema 3.20 Overview .

Example Request

http://on-api.gracenote.com/v3/VideoPopularity?limit=1&api_key=<your-api-key>&tmsId=SH014483860000

Response

<on xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://files.api.gracenote.com/xsd/on_update_videoPopularities_3.20.xsd" schemaVersion="3.20">
  <header>
    <content>On - Updates: videoPopularity</content>
    <created>2020-03-11T22:52:58Z</created>
    <copyright>Copyright 2020 Gracenote, a Nielsen Company. All rights reserved.</copyright>
    <requestParameters>
      <requestParameter name="tmsId">SH014483860000</requestParameter>
    </requestParameters>
  </header>
  <videoPopularityScores>
    <videoPopularityScore id="GN18F41S8EXXK7P" rootId="8797753" country="USA" updateId="1982313814"
    updateDate="2020-03-11T21:55:01Z">
      <score>0.31998</score>
      <scoreDate>2020-03-11T19:23:02.197Z</scoreDate>
      <programs>
        <program>
          <tmsId>SH014483860000</tmsId>
        </program>
        <program>
          <tmsId>SH014737160000</tmsId>
        </program>
        <program>
          <tmsId>SH015697420000</tmsId>
        </program>
        <program>
          <tmsId>SH015697430000</tmsId>
        </program>
        <program>
          <tmsId>SH022896880000</tmsId>
        </program>
        <program>
          <tmsId>SH022896890000</tmsId>
        </program>
        <program>
          <tmsId>SH023041660000</tmsId>
        </program>
        <program>
          <tmsId>SH023041670000</tmsId>
        </program>
        <program>
          <tmsId>SH024066850000</tmsId>
        </program>
      </programs>
    </videoPopularityScore>
  </videoPopularityScores>
</on>

About IDs in Video Popularity

You should use a Program's TMS ID to look up its Video Popularity score. This returns the Video Popularity data and some other IDs as described below:

ID Type	Description
Object ID	Video Popularity Object ID is an alpha-numeric ID that starts with “GN”. Each Object ID is a unique identifier for the combination of Root ID + country + date for a program. These IDs are transient and change every day.. The “object” associated with the Object ID includes all of the relevant Video Popularity score information for the given program. Object IDs are not meant to be used for program lookups in the API.
Root ID	The program Root ID is the main ID associated with a program’s Video Popularity score for a specific country. For example, the Video Popularity score in the US for the movie Titanic is associated with the Root ID for Titanic with US as the country of relevance. All relevant TMS IDs under the given Root ID will have the same Video Popularity score for that country.
TMS IDs	TMS IDs are 14-character alpha-numeric IDs that start with only “SH” or “MV”. The TMS IDs returned for Video Popularity are likely the most relevant for a specific country, but they are not necessarily a complete list. All relevant TMS IDs for a given program Root ID will have the same Video Popularity score.