GN IDs API

Creating and Publishing Images

In GN IDS, you register images separately from programs. However, registered images are not published independently. To publish images, you must associate them with registered programs. After the associated programs are successfully published, the images will be available.

GN IDS-registered images are made available via URLs. Currently, they are not available to Gracenote editors during publishing. Therefore, these images are not included in the Gracenote Certified datasets.

Image Standards

Register images categories, dimensions, and aspect ratios that follow Gracenote conforming image standards. Or you can use non-conforming properties.

The following table lists the properties of GN IDS images. Enum below indicates a predefined value from the Data Dictionary:

Property	Description	Type
Aspect Ratio	Ratio of W	String
Brand Description	Describes the branding applied to the image.	String
Branded	Image contains a brand name or logo. Example: source, channel, network.	Boolean
Category	Category of Image. Must match a Gracenote Image Category to be considered "Conforming".	String
Custom Attribute	Custom key-value pairs for proprietary image attributes. Multiple entry.	-
Date Created	Creation date of the image.	iso 8601 string
Description	Description of the image.	String
H	Height dimension properties of the image. Must match a set of Gracenote image dimensions to be considered "Conforming".	Int
W	Width dimension properties of the image. Must match a set of Gracenote image dimensions to be considered "Conforming".	Int
File Type	Image file format. Example: BMP, PNG, JPG.	Enum
URL	Full, active URL for the image. Used for editorial reference and/or source data delivery. Requires Image Label (URL). Multiple entry.	String
Label	Custom Attribute label text.	String
Languages	Primary languages used in the image. Multiple entry.	Enum
Markets	Applicable demo group/area for the image. Multiple entry.	Enum
Sensitive	Image contains sensitive material.	Boolean
Tags	Source provided tag(s) for the image. Multiple entry.	String
Title	Title of the image.	String
Value	Custom Attribute value text.	String
Presentation GnID	GnID belonging to the presentation that the image will be linked to.	String

Conforming Images

Conforming images adopt standard categories and dimensions used in Gracenote-certified datasets. By registering images as conforming, distribution platforms can seamlessly integrate them into their discovery experiences. The table below shows the relationships between GN IDS conforming images and Gracenote standard images. It also shows how source input categories associated to Gracenote categories for movies and non-movie productions. Program types marked with a checkmark in parenthesis (✓) are not currently curated or delivered in Gracenote data products. However, they are available for registration and Source Data Delivery.

GN IDS Category	GN Movie Category	GN Non-Movie Category	MOV	SHO	EPI	Aspect Ratios
Production Art (Texted)	VOD Art	Banner (L1)	✓	✓	✓	2:3, 3:4, 4:3, 16:9, 2:1, 1:1
Production Art (Textless)	Key Art	Iconic	✓	✓	----	2:3, 3:4, 4:3, 16:9, 2:1, 1:1
Still Frame	Iconic	Iconic (Episode)	✓	(✓)	✓	2:3, 3:4, 4:3, 16:9, 2:1, 1:1
Backdrop	Backdrop	Backdrop	✓	✓	✓	16:9
Title Treatment	Title Treatment	Title Treatment	✓	✓	✓	9:5

Create an Image

• To create an image, use POST/images.

Publish Images to be Gracenote Certified

You can request that the Gracenote Editorial team review your images for inclusion in the Gracenote Certified dataset.

Seasons can also have associated images. These images are sent to the Gracenote Editorial team for review when you request the Season's parent Show to be published.

After the presentation is published, any images you associate with the presentation will be sent to Gracenote only after you request to republish the presentation. See Publishing a Program

To publish images to be Gracenote Certified:

1. When registering an image, set the gracenoteUsage flag to true (default).

Important: The gracenoteUsage flag for registered images is set to true by default. Set the flag to false for any images that should not be considered for inclusion in Gracenote Certified datasets.

1. Associate the image with a presentation (movie, show, or episode). See Associate an Image to a Movie or Show Presentation.
2. Request that the presentation be published. This will send all associated images to Gracenote Editorial for review, and possible inclusion. Use the images endpoint: gnids.gracenote.com/api/v1/images, to POST an image payload to register an image with gracenoteUsage set to true.

Code
 
curl--location 'https://gnids.gracenote.com/api/v1/images' \
--header 'GN-APIKEY: your-api-key' \
--data \
'  {
    "category": "Still Frame",
    "dimensions": {
        "aspectRatio": "16:9",
        "height": 1080,
        "width": 1920
    },
    "fileType": "PNG",
    "gracenoteUsage": true,
    "title": "Example Image",
    "url": "https://example.com/image"
}'

1. Retrieve the imageGnID from the response (assume GNLZZXT00000001) and map it to an existing presentation using the gnids.gracenote.com/api/v1/programImages endpoint. For this example, assume the presentation's GnID is GNLZZXW00000001.

Code
 
curl--location 'https://gnids.gracenote.com/api/v1/programImages' \
--header 'GN-APIKEY: your-api-key' \
 --data \
'[  
{
    "imageGnID": "GNLZZXT00000001",
    "presentationGnID": "GNLZZXW00000001"
}
]'
[{
    "imageGnID": "GNLZZXT00000001",
    "presentationGnID": "GNLZZXW00000001"
}
]'

1. Once mapped, you must publish (or republish if a previous publish attempt was made). To do this, use the gnids.gracenote.com/api/v1/publish endpoint. All images attached to that program will be sent to Gracenote Editorial for review and possible distribution.

Code
 
curl--location 'https://gnids.gracenote.com/api/v1/publish' \
 \
--header 'GN-APIKEY: your-api-key' \
--data \
'{"gnID": "GNLZZXW00000001"
}'

Associate an Image to a Movie or Show Presentation

To associate images with presentations:

1. Create an image via POST/images.
2. View the 200 response body to get the Image's gnID to add the image to a presentation.
3. Add the Image's gnID to a Presentation using POST/programImages.