Data Dictionaries and Controlled Vocabulary
Data Dictionaries
On API provides the following data dictionaries in spreadsheet format. Click on the links below to download these files:
Controlled Vocabularies
On API provides a Controlled Vocabulary endpoint that lists Gracenote-managed (controlled) terms to simplify data indexing and searching. The terms may include extended attributes carrying second-level data (such as rating bodies with rating codes), relationships to other lists or translations/localizations.
The following program value lists are enumerated in the Controlled Vocabulary endpoint:
- Genre, Ratings, Awards, Cast/Crew Roles, Countries.
The following program value lists are documented in the Supplemental Controlled Vocabulary (auto-download):
- Program Types/Subtypes, Title Subtypes, Program Relationships, Release Media. The Supplemental Controlled Vocabulary also includes Gracenote Genre descriptions.
Data Structure and Relationships
XSD: http://files.api.gracenote.com/xsd/on_update_controlledVocabularies_3.22.xsd
Unless stated otherwise, the XPATH in the tables below is relative to: on/controlledVocabularies/controlledVocabulary
| XPATH Element/Attribute |
Description |
Example |
| @cvId |
Object id of the CV item, unique across all vocabularies/lists |
GNR11, CNTRY10, ADV1018, DMA120, GN0001YFXWJWBWF |
| @objectType |
CV item type, denoting specific vocabulary/list |
Genre, Country, RatingAdvisory, Market, VideoDescriptors |
| id |
The id of the CV item as referenced in other endpoints such as Programs or Celebrities. VideoDescriptors are an exception to this and instead contain the descriptor typeId in this field, their cvId being the same as their descriptorId referenced in the other endpoints.
|
11, 10, 1018, 813, GNFMQH6ZGH1477N |
| type |
Additional detail for CV item, if applicable, for example, “Cast” or “Crew” for roleType |
Cast, Crew, Program, Credit |
| lang |
Language code for the value field. Currently defaults to ‘en’. |
en |
| value |
CV item value (list term) in the specified language |
Sitcom, DEU, Action and Rude Humor, San Francisco-Oak-San Jose, Repentance |
| extendedAttributes/ extendedAttribute/ attributeId |
Extended attributes are used for nested values as well as translations. AttributeId can be used for ISO numeric country code (Country CV), rating code (RatingsBody CV). |
276, PG-13 |
| extendedAttributes/ extendedAttribute/ attributeType |
Describes the category/type of the extended attribute value |
translation, code, country |
| extendedAttributes/ extendedAttribute/ attributeLang |
The translation language of the extended attribute value, if applicable |
en, fr-CA, pt-BR, it, de, ja |
| extendedAttributes/ extendedAttribute/ attributeValue |
The value of the extended attribute. Can carry the translated text, 3-letter country code (Country CV), optional description of the rating code (RatingsBody CV) etc. |
Arrependimento, DEU, All ages admitted |
CV Types / Lists
| cvType |
Ref’d by |
Description |
Example |
| RatingAdvisory |
Programs |
Specific terms or phrases which provide specific detail as to portions of the movie/program that may require viewer discretion |
Drug and Alcohol Use, Mature Situations, Coarse Language |
| RatingsBody |
Programs |
The name of a rating body or rating system used to classify content, including classification codes. May include official or unofficial bodies. |
Motion Picture Association (PG, PG-13, R), USA Parental Rating (TVG, TV14, TVMA) |
| AwardBody |
Programs, Celebrities |
The name of an award body that selects nominees and winners of their respective award categories |
Academy Award, Screen Actors Guild Awards |
| AwardType |
Programs, Celebrities |
The category of the award a person or program could be nominated for or win |
Best Actress, Film Editing |
| AwardCategory Mapping |
Programs, Celebrities |
A mapping that associates the award body with the award category name |
Academy award → Actor in a leading role |
| Country |
Programs, Celebrities, Sources, Lineups, Schedules |
3-letter ISO code for country |
DEU, IND |
| GenreImageMap |
N/A, default images for programs with a given genre |
Mapping between genreId to the genre images, including URI to collect those images from Media Cloud |
genreId = 1 (Action) → assets/g1_v9_ab.jpg |
| GenreImage |
N/A, default images for programs with a given genre |
The genre image asset information which includes aspect ratio, height and width |
g1_v9_ab: ratio=3:4, width=1080, height=1440 |
| Genre |
Programs, Organizations |
A category that describes the overall artistic content of a program, including language localizations |
Action, Comedy, Horror |
| Holiday |
Programs |
Specific holidays playing a significant role in the plot/subject of a program |
Christmas, Anzac Day, Halloween |
| Market |
Sources, Lineups |
A designated market area (DMA), also referred to as a media market, is a region of the United States that is used to define television and radio markets - usually metropolitan areas, with suburbs often being combined within |
Cleveland-Akron, New York, Buffalo |
| RoleType |
Programs, Celebrities |
Responsibility of the person in a program/production |
Actor, Host, Animation Manager |
| VideoDescriptors |
Video Descriptors, Programs,
Program Annotations |
Video Descriptor taxonomy language localizations |
Power (en) ↔ Poder (pt-BR) |
| Warning |
Programs |
Content warnings from a legacy content advisory system that predates support of rating bodies in Gracenote data |
Adult Language, Violence |
Localizations/Translations
Translations are available via CV extendedAttributes for the following CV types:
Vocabularies Outside of CV
Controlled Vocabulary endpoint includes larger and/or dynamic lists that are updated more frequently. The following mostly static lists/vocabularies are provided in the Supplemental Controlled Vocabulary (auto-download) document (each line item is a separate tab):
| Endpoint |
List / Vocabulary |
| Programs |
progTypes, subTypes
title_subTypes, Relationships, Release Medium,
Genres (incl. descriptions and movie/sport flags) |
| Sources |
Types, Relationships, Attributes, Reach, Channel Transports |
| Lineups |
Types, Device Types, Channel Tiers, Channel Transports |
| Schedule |
Qualifiers |
| Availability |
Id Type, URL, License, VideoQuality, Provider Data |
API and Example Responses
API: http://on-api.gracenote.com/v3/cv?updateId=0&limit=1000&api_key=<your-api-key>
Controlled Vocabulary XML examples