GVD Endpoints

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.

For a given country, all relevant country context ids that are associated with the same GVD program root id will have the same popularity score.

Gracenote US Video Popularity covers:

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

Gracenote US Video Popularity does not cover:

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

Data Delivery

To get an initial Video Popularity data set and subsequent updates, follow the instructions in Getting Seed Data and Updates. Video Popularity scores for all programs are updated daily. You should check for updates regularly to ensure you are using the latest scores.

Sample Request

Code
 
http://gvd.gracenote.com/v1/video-popularity?program_root_id=GN3XFC0GQMJ0Y1Q&api_key=<your-api-key>&streamId=0&updateId=0&limit=10

For details about this API request, see the Video Popularity API documentation above.

Sample Response

The table below shows parameters that are relevant to video popularity.

Attribute	Description
country	The country of relevance for the popularity score.
program_root_id	GN root id for the program. The main id associated with the score for a given day. All GN context ids associated with a GN root id will have the same score for a given country.
score	Numeric video popularity score value.
score_date	Date of the score.

Active Example

Code
 
<gvd xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://files.api.gracenote.com/xsd/gvd_updates_3.0.5.xsd" schemaVersion="1.0">
  <header>
    <content>GVD - Updates: Video Popularity</content>
    <created>2020-01-03T20:54:27Z</created>
    <copyright>Copyright 2020 Gracenote, a Nielsen Company. All rights reserved.</copyright>
    <requestParameters>
      <requestParameter name="id">GN3XFC0GQMJ0Y1Q</requestParameter>
    </requestParameters>
  </header>
  <gvd_objects>
    <gvd_object>
      <id>GN3XFC0GQMJ0Y1Q</id>
      <type>VideoPopularity</type>
      <update_id>810715149</update_id>
      <update_date>2019-12-28T21:07:29Z</update_date>
      <advanced_discoveries>
        <advanced_discovery>
          <video_popularity_item>
            <id>GN3XFC0GQMJ0Y1Q</id>
            <type>VideoPopularity</type>
            <program_root_id>GN41T8KZGYASH50</program_root_id>
            <country>
              <value>CTR_USA</value>
            </country>
            <score>0.97528</score>
            <score_date>2019-12-28T19:23:30Z</score_date>
            <program_contexts>
              <program_context>
                <id>GN6M0P3XWZCA20X</id>
              </program_context>
              <program_context>
                <id>GN9RRY6HJRVM07E</id>
              </program_context>
              <program_context>
                <id>GNABDBXFVN4TTRY</id>
              </program_context>
              <program_context>
                <id>GNFCPAFP4E7Q7HS</id>
              </program_context>
            </program_contexts>
            <xids>
              <xid>
                <id>17580186</id>
                <type>root_id</type>
                <vendor>tms</vendor>
              </xid>
              <xid>
                <id>SH033567460000</id>
                <type>tms_id</type>
                <vendor>tms</vendor>
              </xid>
            </xids>
          </video_popularity_item>
        </advanced_discovery>
      </advanced_discoveries>
    </gvd_object>
  </gvd_objects>
</gvd>

Inactive Example

Code
 
<gvd xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://files.api.gracenote.com/xsd/gvd_updates_3.0.5.xsd" schemaVersion="1.0">
  <header>
    <content>GVD - Updates: Video Popularity</content>
    <created>2019-12-27T20:34:47Z</created>
    <copyright>Copyright 2019 Gracenote, a Nielsen Company. All rights reserved.</copyright>
    <requestParameters>
      <requestParameter name="id">GN1TPW2QHKV2STK</requestParameter>
    </requestParameters>
  </header>
  <gvd_objects>
    <gvd_object>
      <id>GN1TPW2QHKV2STK</id>
      <type>VideoPopularity</type>
      <update_id>788509313</update_id>
      <update_date>2019-12-17T21:10:09Z</update_date>
      <deleted>true</deleted>
      <advanced_discoveries>
        <advanced_discovery>
          <video_popularity_item>
            <id>GN1TPW2QHKV2STK</id>
            <type>VideoPopularity</type>
          </video_popularity_item>
        </advanced_discovery>
      </advanced_discoveries>
    </gvd_object>
  </gvd_objects>
</gvd>

Schema Diagram