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.

Small Medium Large Master New Master
Aspect Ratio Name Dimension Name Dimension Name Dimension Name Dimension Name Dimension
16x9 H h13 480x270 h12 960x540 h11 1280x720 h10 1920x1080 h8 3840x2160
4x3 H h5 180x135 h3 360x270 h6 720x540 h9 1440x1080 h15 3200x2400
3x4 V v2 135x180 v3 270x360 v4 540x720 v9 1080x1440 v13** 2160x2880
2x3 V v6 120x180 v5 240x360 v7 480x720 v8 960x1440 v12 1920x2880
2x1 H - - - - h1 1024x512 h2 2048x1024 - -

** 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:

Aspect Ratio Orientation Categories
16x9 H Horizontal Banners / Iconics / Episodes / Staple Cast ensemble Key Art / VOD Art Backdrop / Team Banner
4x3 H Horizontal Banners / Iconics / Episodes / Staple Cast ensemble Source Logo (h64 100x64) Series/Sport Logo / Team Banner
3x4 V Vertical Banners / Iconics / Episodes / Staple Box Art / Poster Art-Gallery Key Art / VOD Art Celebrity Headshot / Cast-in Character / Team Banner
2x3 V Vertical Banners / Iconics / Episodes / Staple Box Art / Poster Art-Gallery Key Art / VOD Art -
2x1 H Horizontal Banners / Iconics / Episodes / Staple - Key Art / VOD Art -
1x1* Square Banners / Iconics - Key Art / VOD Art -

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. 


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

HTTP Response Code


200 – OK

Request returned successfully

400 - Bad Request Request problem, typically missing or invalid request parameters. Check the response body for more detailed, API-specific error codes (see Error Codes in Response below).

401 - Unauthorized

The request requires user authentication.

403 - Forbidden You have not been granted permission to access the requested method or object.
403 - Not Authorized The API key associated with your request was not recognized or the signature was incorrect.
403 - Account Inactive The API key you are using to access the TMS API has not been approved or has been disabled.
403 - Account over Queries per Second Limit The API key you are using has attempted to access the api too many times in one second.
403 - Account Over Rate Limit The API key you are using has attempted to access the api too many times in the rate limiting period.
403 - Rate Limit Exceeded The service you have requested is over-capacity.

404 - Not Found

The server has not found anything matching the request URI. 

500 - Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

504 - Gateway Timeout

The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

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.



1001 missing_required_parameter
1002 invalid_parameter_value
1003 invalid_boolean_value
1004 invalid_image_parameters
1005 invalid_lineup_id
1006 invalid_int_value
1007 invalid_postal_code
1008 invalid_root_id
1009 invalid_country
1010 invalid_person_id
1011 invalid_station_id
1012 invalid_series_id
1013 invalid_tms_id
1014 invalid_sports_id
1015 Message invalid_market
1020 malformed_date_value
1021 date_value_too_granular_minutes
1022 start_date_too_small
1023 start_date_too_large
1026 date_range_too_small
1027 date_range_too_large
1028 season_invalid
1029 season_empty
2002 missing_resource
2003 multiple_resources_invalid
2004 path_incomplete
3001 internal_sever_error