• Register

Image Metadata

Important: This site is the API Gateway for Gracenote Video and Sports. As of September 08, 2026, the documentation and API explorers (I/O docs) for active products will move to the new Gracenote Developer Portal. Please use this new portal moving forward. Set up your new dev portal account using the login email for this site. The legacy documentation on this site will remain until further notice.  Please contact your Gracenote representative or Gracenote Support for assistance.

Image categories:

  • Banner – source-provided image, usually shows cast ensemble with source-provided text
  • Banner-L1 - same as Banner
  • Banner-L2 - source-provided image with plain text
  • Banner-L3 - stock photo image with plain text
  • Banner-LO - banner with Logo Only
  • Banner-LOT - banner with Logo Only + Text indicating season number
  • Iconic - representative series/season/episode image, no text
  • Staple - the staple image is intended to cover programs which do not have a unique banner image.
  • Cast Ensemble - cast ensemble, no text
  • Cast in Character - individual cast member, no text
  • Logo - official logo for program, sports organization, sports conference, or TV station
  • Box Art - DVD box art, for movies only
  • Poster Art – theatrical movie poster, standard sizes
  • Scene Still – movie photos, legacy sizes
  • Photo - same as Scene Still
  • Photo-headshot - celebrity image

Image tiers:

  • Series – image represents of series, regardless of season (banner, iconic, staple, cast, logo)
  • Season - image represents specific season of series (banner, iconic, cast, logo)
  • Episode - image represents specific episode of series (iconics only)
  • Team Event (New) - image represents team vs. team events (banner)
  • Organization - image represents organization associated with sport (logo)
  • Conference - image represents conference associated with team (logo)
  • Sport - image represents the sport associated with a program (banner, iconic)
  • Sport Event -  image represents the sport event associated with a program (banner, iconic)
  • College - image represents the college associated with a program (logo)
  • Team - image represents the team associated with a program (logo)
  • Note that movie, celeb, and station images do not include tier info

The following program types currently have images that contain a tier value:

  • Miniseries
  • Series
  • Sports

The following program types do NOT contain images with a tier value:

  • Paid Programming
  • Preview

The following program types MAY contain images that contain a tier value. To date, Episode is the most common value:

  • Special
  • Sports non-event

Image text, based on category:

  • text=yes:  Banner (all variations), Program Logo, Logo, Box Art, Poster Art
  • text=no:  Iconic, Cast Ensemble, Cast in Character, Scene Still, Photo, Photo-headshot

Branded images (per January 14th 2019)

  • Gracenote will collect branded images for Banners and VOD image types when provided by source.
  • A program can have more than one branded image to account for availability in more than one market/programming service
  • No back population will happen at this time
  • The program details call will always deliver the unbranded banner/image.
  • Branded images can be recognized by additional identifiers “branded”, "prgSvcId" and "callsign"
  • Identifying that the image is branded including the programming service whose logo is on the image.

Field / object

Type

Notes
uri string relative path to image source file;
may contain generic image reference if program-specific image not found
height string image height, in pixels
width string image width, in pixels
size string new in v1.1; Sm, Md, Lg, Ms; see Image Sizing for details; empty for legacy-sized movie images
aspect string new in v1.1; 1x1, 2x3, 3x4, 4x3, 16x9; empty for legacy-sized movie images
text string new in v1.1; yes/no indicator of text on image content; based on category as noted above
primary boolean primary=true indicates preferrred image; if field not present, indicates secondary image
category string image type (e.g., Logo, Parent Logo, Banner)
tier string indicates relative program level (Series, Season, Episode) for TV program images only
branded Object Branded images include the show network logo on program banners and VOD art. Available in the All program images endpoint.
   prgsvcID string

The programming service whose logo is on the image.
   callsign string

The service callsign whose logo is on the image.
caption Object Image caption, where available. 
content string Caption text; may include title, person name, year
lang string 2-letter language abbreviation code (e.g., 'en'=English, 'sp'=Spanish); see Language Code reference for full listing of codes
personIds string [ ] for Cast Ensemble and Cast in Character images only: list of personIds portrayed in image, in left to right sequence; matches order in which names are listed in caption

Example I 'Branded'

 {
"width": "960",
"height": "1440",
"uri": "assets/p8130405_b_v8_ao.jpg",
"size": "Ms",
"aspect": "2x3",
"category": "Banner-L1",
"text": "yes",
"primary": "true",
"tier": "Series"
"branded": {
"prgSvcId": "10098",
"callsign": "CBS"
},
},

Example II

{
  "width":"120",
  "height":"180",
  "caption":{
    "content":"Tracers (2014)",
    "lang":"en"
  },
  "uri":"assets/p11293563_p_v6_aa.jpg",
  "size":"Sm",
  "aspect":"2x3",
  "category":"Poster Art",
  "text":"yes",
  "primary":"true"
}