Welcome to the GN IDS API. In addition to this documentation, you can find information and resources on the Gracenote Help Center.
The Gracenote ID Distribution System (GN IDS) is a platform to help you manage and optimize the distribution of program metadata using Gracenote IDs. This platform is available as an API described in this guide, and as a web application.
With GN IDS, you can submit movies, shows, and related content along with metadata and imagery to Gracenote. Once submitted, you can request that Gracenote review and publish your content to Gracenote-licensed datasets.
GN IDS makes distributing content easier on a global scale. Using GN IDS, you can create programs, metadata, and images that are associated to Gracenote IDs and publish them to Gracenote data licensees. This enables streamlined distribution across the top MVPDs, OTT platforms, CE devices, and digital services that rely on Gracenote's video metadata and IDs. Gracenote IDs are the most widely used identifiers across the video entertainment industry globally. Gracenote Certified Video data currently covers 85+ countries.
GN IDS provides standard REST API methods to register, publish, and deliver program metadata. The methods operate on different endpoints to support various program types, images, and catalogs for flexible organization and delivery.
You can run these methods directly via curl command or in an HTTPS call. Include your sourceID (provided by Gracenote) in the request. For example:
Code
Concepts
The following concepts are used throughout this document.
Catalog: A container to organize programs and selectively entitle them for delivery (distribution) to Gracenote data licensees.
Certified data: Standard program information curated by the Gracenote editorial team.
Movie: A program of a theatrical movie release.
Presentation: One or many representations of a single program version that require variations in metadata, typically for end-user consumption. Examples include localizing metadata for different languages and target markets or special marketing promotions.
Program: A movie or show.
Program Summaries: A paginated collection of summaries for programs in a source's catalog.
Root: High-level, conceptual representation of a video program. A root can have one or many associated versions.
Series: A type of show that has one or more seasons and episodes.
Show: A TV program, sports event, or similar program that is not a movie.
Source data: Program information you provide through GN IDS to supplement Gracenote data. For example, additional information about a program not covered by Gracenote-certified data. Some examples are more extensive descriptions, additional images, content variants of the same program, and derivative content that Gracenote supports in certified data. Supported programs include movies, shows/series, and episodes.
Version: Content variants that cause distinct changes in video programs or episode structure. For Movies, these include both technical changes (for example, 3D, IMAX) or creative changes (for example, extra scenes, dubbed audio). For Shows and Series, versions typically result from similar changes to the programs or to a Series structure, such as different season and episode configurations (sometimes called repackaging).
Workflow
The GN IDS metadata workflow has three key activities shown in the diagram below:
- Register (Create) Programs
- Publish Programs
- Deliver Programs
Register Programs
Use GN IDS to register source data with Gracenote. GN IDS supports a wide range of metadata for each program type. Gracenote validates metadata on registration to ensure you have provided a minimum set of values.
Register a Program Root, Versions, and Presentations
You can register distinct content variants of the same program using GN IDS, including repackaging and metadata variations. Use this to organize and differentiate your content and metadata for distribution. You can specify programs as versions or presentations of a previously registered program root.
Publish Programs
Publishing is making your registered programs available for distribution in Gracenote datasets. When you request the publishing of your registered program presentations, GN IDS puts them in a queue for ingestion and editorial review. The publishing process links your data to corresponding programs in Gracenote databases. Programs that you request to publish remain private until the publishing process is successful. Publishing a program:
- Associates it to its corresponding TMS ID in the Gracenote-certified dataset.
- Makes the data available to entitled distribution platforms via the Source Programs Endpoint. This requires special arrangement with Gracenote.
Note: If you change a published program, you can request that Gracenote republish it with your changes. Gracenote will evaluate the changes before republishing. Update requests are subject to Gracenote metadata standards and editorial approval.
When you request to publish a program, GN IDS notifies Gracenote editors to associate your program with its corresponding Gracenote-certified program using Gracenote TMS IDs. See the image below for an example showing this process.
In the following hypothetical example, the source provider is Disney. Using GN IDS, the Disney media team created a new presentation of the original "The Empire Strikes Back" with an external ID of VWXYZ. Gracenote editorial staff linked this presentation to the TMS ID MV000191730000, the ID of the original 1980 USA theatrical version of this program. The example also shows the TMS ID mapping of the 1997 Special Edition for a new presentation with external ID QRSTU.
Deliver Programs
Gracenote delivers your programs in two ways:
- Certified Data: Gracenote metadata for published programs is available in Gracenote-certified datasets.
- Source Data Delivery: Your metadata for published programs is made available using the Source Data Delivery process. This process uses a streamlined set of APIs related to Gracenote On API.
For additional information, see the On API documentation.