Media Cloud

Overview

Gracenote Media Cloud provides on-demand delivery of entertainment images to Gracenote customers. Our service is based on a scalable and highly reliable Content Delivery Network (CDN) platform that has served billions of images.

Audience

This document introduces the Gracenote Media Cloud to developers who wish to build rich user interfaces using images hosted by Gracenote.  Media Cloud provides images to Gracenote clients receiving image references in various On products.  We distribute various image categories, including:

  • Celebrity Images
  • TV Banners
  • DVD Box Art
  • Movie Posters
  • Iconic Images
  • Episodic Images
  • Programming Service Logos
  • Sport Logos

Important Terminology

  • Aspect ratio - The proportion of an image’s width to its height is considered the image’s aspect ratio.
  • API key - This is the identifier that Gracenote uses to grant clients access to the development server. 
  • URI - Uniform Reference Identifier, used in the On Product suite to identify the filename and pathname of a given image asset.
  • CDN - Content Delivery Network, a distributed, redundant network of file servers that serves online content quickly and reliably.

Accessing the APIs

To use the API, structure the URLs as follows:

http://<HostServer>/<location>?<RequestParameter>

Server Access

Sample access to Media Cloud is provided with a Mashery API key through a common development domain. 

The api_key parameter is required for Sample use only and is provided to the client by Gracenote.  If the api_key parameter is not present, the query will return an error message, stating that the action is not authorized. 

  • Sample Plan- http://developer.tmsimg.com/ 

Production access requires a client subdomain.  This is referenced below as <ClientSubdomain> and will be provided by the Gracenote team once the client is ready for production service. The api_key parameter is not used in the Production environment and will be ignored if included.  

  • Production - http://<ClientSubdomain>.tmsimg.com/

URIs

Image URIs are provided in your data products – On, On Connect, On API, etc.. 

In the On product suite, they are referred to as URIs.  Ex.<URI>AllPhotos/59720/59720_aa.jpg</URI>

Image Resizing

Media Cloud allows for optional image dimension parameters, w for width, or h for height, which allow on-the-fly image resizing.

Please note that only ONE of the height and width parameters should be used, in order to allow the service to return an image with its native aspect ratio.  If both height and width are specified, only the width parameter will be used.

Images can be scaled to larger than the standard sizes, but we do not recommend doing so in general because image resolution will suffer.

Once a resized image has been requested once, it will be cached in our distributed CDN to minimize response time for further requests.

Error Messages

Incorrect File/Pathname or Missing Image:

If an incorrect URI is provided, the client will receive a 404 error page containing a blank 1x1 image.

Missing/unauthorized API Keys:

If the client API key is missing or invalid for development server calls, the development server will respond with the message "Developer Inactive". As stated previously, the API key is not required for production Media Cloud access on a customer’s unique sub-domain.

If the client API key is valid but not authorized for Media Cloud (i.e., Public Plan keys), the development server will respond with the message "Not Authorized".

Image Dimensions 

Gracenote will provide the largest image possible based on availability from sources.  The table below indicates the expected maximum dimensions for each aspect ratio.

Orientation

Ratio

Width x Height 

Square

1:1

3000 x 3000

Horizontal

4:3

1440 x 1080

Horizontal

16:9

3840 x 2160

Horizontal

2:1

2048 x 1024

Vertical

2:3

960 x 1440

Vertical

3:4

1536 x 2048