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 table 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 Aspect Ratio
Name Dimension Name Dimension Name Dimension Name Dimension
h13 480x270 h12 960x540 h11 1280x720 h10 1920x1080 16x9 H
h5 180x135 h3 360x270 h6 720x540 h9 1440x1080 4x3 H
v2 135x180 v3 270x360 v4 540x720 v9 1080x1440 3x4 V
v6 120x180 v5 240x360 v7 480x720 v8 960x1440 2x3 V

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

  • Channel/source logos: 4x3 horizontal
  • Banners: all (2x3, 3x4, 4x3, 16x9)
  • Iconics: all (2x3, 3x4, 4x3, 16x9)
  • Episodics: 4x3 horizontal, 16x9 horizontal
  • TV program logos: 4x3 horizontal
  • Movie DVD box art: 2x3 vertical
  • Movie poster art: 2x3 vertical
  • Celebrity headshots: 3x4 vertical
  • Cast in character: 3x4 vertical
  • Cast ensemble: 4x3 horizontal, 16x9 horizontal
  • Sports logos: 4x3 horizontal

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

Description

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.

Code

Message

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