Media Cloud

Overview

Gracenote Media Cloud provides on-demand, web-scale 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 to end users. 

Audience

This document introduces the Gracenote Media Cloud to developers who wish to build rich user interfaces using images hosted by Gracenote.  Media Cloud is available to Gracenote clients across all of the geographies we serve, and it hosts all image categories, including:

  • Celebrities
  • DVD Box Art
  • Movie Posters
  • TV Banners
  • Iconics
  • Source Logos
  • Sports Logos
  • Showcards

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>

Host Server

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

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

For use with production Media Cloud hosting, every client will receive a unique subdomain.  This is referenced below as <ClientSubdomain> and will be provided by the TMS team once the client is ready for production service. Production image access does not require use of an API key.

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

Location

Location refers to the directory structures and file name as specified in the On products.  In the On product suite, these locations are referred to as URIs.  Examples include:

  • tvbanners/v5/AllPhotos/8218867/p8218867_b_v5_aa.jpg
  • celebs/v9/AllPhotos/87269/87269_v9_ba.jpg
  • dvdboxart/v6/AllPhotos/3542039/p3542039_d_v6_aa.jpg

Request Parameters

Only two types of request parameters are expected by Media Cloud – image dimensions, and the client API key.  If a developer provides request parameters other than h, w, and/or API key, they will be ignored.

  • Image Dimensions

Image Dimension request parameters – w for width, or h for height – are optional, and allow on-the-fly image sizing both in sample and production use. 

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.

  • API Key

The api_key parameter is required for Sample use only; it  is provided to the client by Gracenote when access to the developer site is granted.  If the api_key parameter is not present, the query will return an error message, stating that the action is not authorized.

The api_key parameter is not used in Production environment; it will be ignored if included.  Images will be accessed via customer-specific sub-domain, with no need for API key.

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".

Appendix A: Image Dimensions

The table below indicates the expected maximum dimensions for images in the Media Cloud repository.

Photo orientation

Naming convention

Dimensions (w x h)

Aspect Ratio

horizontal

432x288

3x2

horizontal

108x72

3x2

horizontal

h3

360 x 270 pixels

4x3

horizontal

h4

90x67

4x3

horizontal

h5

180x135

4x3

horizontal

h6

720x540

4x3

horizontal

h7

267x200

4x3

horizontal

h9

1440x1080

4x3

horizontal

h10

1920x1080

16x9

horizontal

h11

1280x720

16x9

horizontal

h12

960x540

16x9

horizontal

h13

480x270

16x9

horizontal

h14

240x135

16x9

Vertical

288x432

2x3

Vertical

72x108

2x3

Vertical

v2

135x180

3x4

Vertical

v3

270x360

3x4

Vertical

v4

540x720

3x4

Vertical

v5

240x360

2x3

Vertical

v6

120x180

2x3

Vertical

v7

480x720

2x3

Vertical

v8

960x1440

2x3

Vertical

v9

1080x1440

3x4