Reference

DateTime Formatting

DateTime fields in requests should be formatted according to ISO 8601 standards.  DateTimes should be specified in Coordinated Universal Time (UTC), or can be specified in local time with UTC offset.  Note that offsets must be adjusted for Daylight Savings Time, when in effect in local timezone. 

DateTime fields in responses will be formatted according to ISO 8601 standards, and specified in UTC.  To display data in local timezone, UTC offset must be applied to response data.

Example 1:

To specify December 1, 2012, 3pm Eastern Time in request parameters, either of the following formats are valid: 

• UTC: 2012-12-01T20:00Z
• Local (EST) with offset: 2012-12-01T15:00-05:00

Example 2:

To specify August 1, 2012, 3pm Eastern Time in request parameters, either of the following formats are valid :

• UTC: 2012-08-01T19:00Z
• Local (EDT) with offset: 2012-12-01T15:00-04:00  (note offset change due to Daylight Savings Time in effect)

Image Sizing

The tables below defines the sizes associated with Small, Medium, Large, and Master values that are used for the ‘imageSize’ input parameter. The naming convention (h5, v6, v9, etc.) can be seen in image filenames included in responses.

** V13 Master size is supported for all images categories except celebrity headshot (Master is v9)

TV banners and Iconics are available in all aspect ratios; other image categories are available in aspect ratios as follows:

* Only the largest size rendition available will be provided on programs with square images.

Image URI output change per 2021/02/17

Gracenote is in the proces of retiring the smaller size image renditions and sizes on the Media Cloud, overtime there will only be 1 master size available on the Media Cloud, effective February 16th, 2020. To keep supporting sizes associated with Small, Medium, Large we are making changes to how we output image URI's in OnConnect.

Impacted endpoints

All endpoints where 'imageSize' is a valid parameter for images.  *Note: If you parse the URL or modify it, please verify the new format will not cause problems. 

Example

Before:	After:
"preferredImage": { "width": "240", "height": "360", "uri": "assets/p9181462_b_v5_aa.jpg", "category": "Banner-L1", "text": "yes", "primary": "true", "tier": "Season" }, "preferredImage": { "width": "480", "height": "720", "uri": "assets/p9181462_b_v7_aa.jpg", "category": "Banner-L1", "text": "yes", "primary": "true", "tier": "Season" },	"preferredImage": { "width": "240", "height": "360", "uri": "assets/p9181462_b_v9_aa.jpg?w=240&h=360", "category": "Banner-L1", "text": "yes", "primary": "true", "tier": "Season" }, "preferredImage": { "width": "480", "height": "720", "uri": "assets/p9181462_b_v9_aa.jpg?w=480&h=720", "category": "Banner-L1", "text": "yes", "primary": "true", "tier": "Season" },

URL/URI construction

The URI examples above (e.g. assets/p9181462_b_v9_aa.jpg?w=480&h=720) will be combined with the customer specific Media Cloud subdomain URL (e.g. customerx.tmsimg.com/...). that has been configured by Gracenote. When requesting the image from Media Cloud, this service will automatically resize and return the image in the expected size. 

Timezone Lineups

TMS provides a set of default channel lineups for US and Canadian timezones. These provide a collection of common stations, and can be used to get scheduling information without prompting users for postal code or a choice of cable/satellite providers. Around 110 stations are included in the US timezone lineup, and around 90 stations in Canada's timezone lineup. These lineup ids can be used to retrieve TV schedule information specific to each timezone.

Here are the available timezone lineupIds:

• USA-DFLTE - eastern time (US)
• USA-DFLTC - central time (US)
• USA-DFLTM - mountain time (US)
• USA-DFLTP - pacific time (US)
• USA-DFLTH - Hawaii time (US)
• USA-DFLTA - Alaska time (US)
• CAN-DFLTEC - eastern time (Canada) 
• CAN-DFLTMC - mountain time (Canada) 
• CAN-DFLTCC - central time (Canada) 
• CAN-DFLTPC - pacific time (Canada) 

Error Handling

If an API call results in an error, we will return an HTTP status code in the header fields and in the message-body, if applicable. A response code of 200 (OK) is returned for all requests that are successfully understood and processed. While using our APIs you may receive the following HTTP errors:

HTTP Codes

Error Codes in Response

Error codes which could be returned in the response body are usually indicative of a problem with the request, and accompanied by HTTP status code 400. See chart below for details.