Gracenote Customer Integration

Welcome to IVA! Gracenote and IVA have partnered to make integrating video into your site as easy as 1, 2, 3, 4. This page will walk you through making a link to a video.

Step 1: Get your credentials

Your customer service representative at Gracenote should provide you with the following when you sign up:

  • Customer ID ( this is your comany’s account number)
  • Security Token ( do not share this with anyone outside your organization)
  • Developer ID (used to access the Data from IVA’s Web Service)

Note: Please keep this information in a safe place as you will need it to access content at IVA.

Step 2: Get the data

Gracenote provides their customers with IVA’s database of Published IDs. Select the Published ID for the title you want video for. This ID is only the Main Entertainment Program ID. For a full map of Gracenote ID’s to all of the related Entertainment Programs including different language versions and alternate content, please contact IVA’s Support Team for FTP credentials to the mapping table.

Gracenote Data Dictionary

Note: Gracenote refers to IVA’s Published ID’s as “IVA Pinpoint ID”. Any documentation on their site will refer to it as that and any documentation on this site will refer to it as the PublishedID.

Step 3: Get available encodes

Each title in our database is encoded in multiple formats designed to meet the wide variety of screens and operating systems used by consumers to watch content. Not every encode is available for every title; HD was not around for older films, for example.

Insert the Published ID for the title you want (244133 in the example below) plus your Developer ID into the URL shown below and IVA OData API will return back the XML with all of the available encodes. Decide the FileType and Rate you want. Get the URL property for that FileType and Rate. You will need this to make a working link in Step 4. Here is the URL:$filter=PublishedId%20eq%20244133&developerid={your-id}

The table below lists the properties that are returned in the XML from the query. Use any of these properties to make your query more specific.  Example:  If you just want to know if a title is available in HD (Rate = 2500):

Encodes Entity (OData 1.0/2.0)

A collection of Encodes available from IVA to use with the Video API or IVA’s HTML5 or Flash Video Players.
PublishedIdUnique ID for the VideoAsset.
StreamingFlavorIdID for the type of encode.
DateDigitizedThe date in which the video was last encoded.
rateThe Kbps target for the encode. Ex: 450 = 450 Kbps of the combined audio and video tracks bitrate.
FileTypeThe video format of the encode. Ex: MP4
URLContains either a URL for the asset without a customerID or "see video api documentation"
RemoteURLTrue or False. Determines if the content is redirecting to another server for delivery. The overwhelming majority of encodes are ‘false’, meaning they are not being served from a 3rd party. Note: Content not served from IVA is free of charge and not included in the GB billing reports.
ProprietaryCustomerIdUsed only for Subscribers who use IVA to encode their own content. The default value is -1 meaning not proprietary.
IDUnique ID for the encode.

Step 4: Make a link to the video

To make a link to a video you need your Customer ID, your Security Token, and the base URL you got from the Encodes Entity above.

  • Take the base URL (Encodes Entity)
  • Add your Customer ID
  • Add a time to live (e)
  • Take all 3 (base + CustomerID + time to live), run an MD5 hash using your Security Token and append to URL (h)

When finished your URL should look like this:{CustomerID}&videokbrate={kbrateFromEncodes}&publishedid={PublishedIDoftheAsset}&e=1291562741&h=1e7096ca5689034f5804be881c3c8c2d

For more information, including a full description of all the parameters and creating the hash code please see this page: Video-API

We look forward to working with you! Should you have any questions please feel free to email our Support Team.

Thanks for choosing Gracenote and IVA!

Gracenote mapping table data dictionary

This data dictionary is for Gracenote data subscribers only.  Please contact your Gracenote Representative for access to this feed. This feed is used to integrate IVA trailers with Gracenote data.

IVA now has an updated V4 feed. Please be sure you are using the latest version.

Field Name Definition
GracenoteIDs (not null)This is the principal Gracenote identifiers for a root level program.
WorkTUI – Gracenote WorkTUI mapped to this program  
WorkTUITAG – Gracenote WorkTUITAG mapped to this program
SeriesTUI – Gracenote SeriesTUI mapped to this program
SeriesTUITAG – Gracenote SeriesTUITAG mapped to this program
SeasonTUI – Gracenote SeasonTUI mapped to this program
SeasonTUITAG – Gracenote SeasonTUITAG mapped to this program
IVAID_MAIN  (not null)The Root level record unique identifier.Commonly referred to as the Entertainment Program. This will always correspond to the root level record.. For TV, this corresponds to the Series root level record.
IVA_AssetID (not null)Child record  unique identifier. Commonly referred to as an VideoAsset. This corresponds to any record which promotes an Entertainment Program. For TV, this corresponds to all children under a series.
NOTE: This is the same as the Gracenote_ID_Main if IVA_AssetID is a root level record.
MediaTypeThe MediaType determines the type of entertainment  the VideoAsset belongs to. For example: Movie , Song , TV Series ,Movie Clip, etc
TitleThe title of the Artistic Work. Ex: “Green Lantern, The” or title of the VideoAsset. Titles have their articles placed at the end of the string.
Modified DateThe last time the Video Asset or any of it’s related data has been modified. This includes but is not limited to adding alternate Ids, new encodes, new VideoAssets added, cast changes, etc.
ExpirationDate (nullable)Some video content is provided to IVA with an expiration date where a video asset is no longer allowed to be viewed online.  This field will contain a date for the Default VideoAsset if an expiration date is set. Otherwise, the expiration date will be NULL.
OkToEncodeAndServeFrom time to time, content owners need to restrict a video from being displayed. This boolean property is used to disable content from being served from IVA servers. Default = True.
LanguageSpokenReference to Language entity. This property describes the primary language spoken in the VideoAsset which is not particularly the same as the Language as the IVAID_MAIN record.. This property is especially useful for localizing video content in other countries in combination with TargetCountry property.  Default = en NOTE: These values are based off of the ISO 639-1 language codes.
Language SubtitleReference to Language entity. This property describes the primary language subtitled in the Video Asset which is not particularly the same as the Language as the IVAID_MAIN record. This property is especially useful for localizing video content in other countries in combination with TargetCountry property.  When the video asset does not have subtitles, this property is set to a blank string.   NOTE: These values are based off of the ISO 639-1 language codes.
Sequence  (nullable)This element is only for Gracenote_ID_V or IVA Video Assets.. This property is used primarily used for Television Seasons and Television Episodes to order child elements. For an episode Video Asset, this will be an episode number, for a season Video Asset this field represents a season number. This is NOT to be confused with overall sequence numbers, which this field is not.  Default = NULL
TargetCountryReference to Country entity. This denotes whether the VideoAsset was made for a specific country. This property is rarely used.NOTE: These values are based off of the Alpha 2 Country Codes
PromotesPublishedidWhen a Video Asset is a child of another Video Asset, it’s PromotesPublishedId will contain the IVAID_AssetID of it’s parent. This is particularly useful for Televion Seasons (with Television Series parents) or Television Episodes (with Television Season parents).
DefaultVideoAsset (Removed in v4 feed)Determines if the VideoAsset is the default video played for the EntertainmentProgram denoted by the PromotesPublishedId property. A true value indicates this is a default video asset.
WarningFlag  (mature)  This denotes a red band trailer or explicit content.  For most content this is set to false.
HdSourceThis will be set to True if the digital master’s width is greater than 1260 pixels wide (720p HD). 
SourceWidthThe width of the digital master.  Default = -1 when information is not available.
SourceHeightThe height of the digital master. Default = -1 when information is not available.
isIvaContentOn rare occasions studios provide links to video content rather than high quality source materials.  Content that points to studio links usually has limited formats and IVA cannot guarantee the quality of delivery.  This property denotes whether IVA is delivering the video for the Default VideoAsset for the program. Default = True.
StreamlengthinSecondsThe length is seconds of the VideoAsset for the Entertainment Program. This is useful to distinguish whether IVA has a VideoAsset for the particular Entertainment Program.  Default = -1.
ImageUrlA 320×240 photo still captured from the Video Asset.
EncodingsStreamingFlavor: ID for the type of encode.
Rate: The Kbps targe for the encode. EX: 450 = 450Kbps of the combined audio and video tracks bitrate.
DateDigitized: The date in which the video was last encoded.
FileType: The video format of the encode. Ex: MP4
Width: Max width for this particular video.
Allow Ads (V2, V3, V4 Feeds Only)Indicates whether this video must enable ads
Requires IVA Player (V2, V3, V4 Feeds Only)Indicates whether this video requires ONLY using the IVA Player.
Region Restrictions (V2, V3, V4 Feeds Only)Country – Name of the Country for this restriction.
Country Code – ISO_3166-1 Alpha 2 digit code for this country.
Allowed – Indicates whether this country is allowed to display this video. If false, this content CAN NOT be played for this country.
Group Permission ID (v3, v4 feeds only)Indicates the group id a customer is required to belong to in order to access this content. Please contact for more information.