OnConnect Migration - FAQ

Migrating from v1 to v1.1

As part of improving our product, we have launched a brand new version of our API that includes a more stable and consistent experience. This enhancement also makes program and schedule data updates available sooner than OnConnect v1 currently provides.

We hope you like the improvements. While v1.1 was designed to be fully backward compatible with v1, we've made a few changes and want to let you know about them.

The new endpoints will be available on February 9, 2015.

General API Changes

  • Same endpoints available, with newer version accessible using v1.1 in URL
  • Improved data pipeline, with continuous refresh of global schedule and program data
  • Additional imagery and metadata for many international programs
  • Backward compatible with new fields added in some responses to improve object consistency across endpoints 
  • All keys will work with both v1 and v1.1 URLs, through the end of the migration period (May 11, 2015). At that point, v1 calls will be redirected to v1.1 endpoints.
  • Issues identified during migration period will be noted, along with fix status, on Changelog page. 

Individual API Method Changes

API Method Change
Series Episodes

Due to large number of episodes available for some series, v1.1 response will be limited to a maximum of 100 episodes. However, new paging parameters similar to Program Search will be available to allow retrieval of episodes in batches using multiple calls.

When paging parameters (offset/limit) are specified, response format will be modified to include an outer wrapper object with totalHits count and hits array (see v1 Program Search response for example). Response will continue to be sorted by season/episode number.

Series/Program Details Field 'totalEpisodes' now omitted when value is 0.
Find Theatres Response limited to 100 theatres max.
Find Theatres New zipcode database used; zipcode centroids may differ slightly resulting in minor changes to number of theatres fournd in radius search; radius may be adjusted to capture more/fewer theatres.
Image Captions For TV banners and iconics, caption is now omitted; if desired for display purposes, program title may be used as caption for these image categories. Movie posters and DVD box art images continue to include movie title + (release year) as caption. Cast images and scene stills will continue to include image-specific text in caption field, when available.
Image URIs Abbreviated '/assets' path is now used for all images, with exception of celebrity photos and station logos.  All paths will continue to work with Media Cloud image retrieval.
Station Details LineupId is no longer required as a request parameter to receive affiliate station information in response.
Program Genres Genre listing will be available in English only, which is current default.  As in v1, genres within program records will continue to be output in English, regardless of program title and description language.

Celebrities on Talk Shows
by Day 

Celebrity.preferredImage will no longer be included in response.  A separate call to Celebrity Details or All Celebrity Images, using personId, can be made to retrieve images. 
Celebrity Details In credits, program.type field  (e.g., 'Show', 'Movie') is now capitalized, for consistency with program.entityType.
Program Search Keyword search is deprecated. Search with or without lineupId parameter works slightly differently. See program search page for more details.

Data object changes

Object.field Change
image.text

New yes/no field indicating whether text is present on program images; not included on station logos and celebrity headshots.  Value is based on image category, and used in conjunction with existing 'imageText' parameter for preferredImage and Program Images responses. 

image.size New field matching values in request parameter 'imageSize': Sm, Md, Lg, Ms.  See Image Sizing for more info.
image.aspect New field matching values in request parameter 'imageAspectTV': 2x3, 3x4, 4x3, 16x9.  See Image Sizing for more information.
program.releaseDate Previously available only in Future Releases, represents earliest release date (yyyy-mm-dd) for movies. May be truncated to yyyy when no specific date available. 
lineup.name 1. Lineup location will no longer be auto-appended to name; many lineups already include location as part of name, leading to redundancy in output.  Location field is returned as part of lineup object, and can be appended for display, if desired.
2. Lineup name in v1 includes type designation of '- Cable' and '- Digital'.  v1.1 will include ' - Satellite' designation in name for consistency. 
3. OTA lineup names will change from 'Local' to 'Local Over the Air Broadcast'
station.affiliateId
station.affiliateCallSign 
Previously available only in Station Details and Lineup Channels, these fields are now included wherever station object is available

Error Mapping Changes

HTTP
Code
v1.1 / v1

OnConnect Error Code Message text - v1.1
Message text - v1
400 1001 missing_required_parameter Missing required parameter: {xxx}
400 1002

invalid_parameter_value

Invalid parameter value: {xxx}
400 1005 invalid_lineup_id Invalid lineupId: {xxx}
400 1008 invalid_root_id Invalid rootId: {xxx}
400 1010 invalid_person_id Invalid personId: {xxx}
400 1011 invalid_station_id Invalid stationId: {xxx}
400 1012 invalid_series_id Invalid seriesId: {xxx}
400 1013 invalid_tms_id Invalid tmsId: {xxx}
400 1014 invalid_sports_id Invalid sportsId: {xxx}
400 1020 malformed_date_value Malformed dateTime: {xxx}
Messages no longer used in v1.1
   200 (v1.1)
400 (v1)
1007
1008
postal code and country codes not validated in v1.1; will return valid empty response when no matches found

No lineups found for postalCode: {xxx}
Invalid countryCode: {xxx} ;

   200 (v1.1)
400 (v1)
1028
1029
v1.1 will return valid empty response when season data not found for specified season Invalid season: {xxx}
Empty season: {xxx} 

1003 deprecated in favor of general 1002 message Invalid boolean value: {xxx}

1004 deprecated in favor of general 1002 message Invalid image parameters: {xxx}

1006 deprecated in favor of general 1002 message Invalid int value: {xxx}

1021 deprecated in favor of general 1002 message Date value too granular: {xxx}

1022 deprecated in favor of general 1002 message Start date too small: {xxx}

1023 deprecated in favor of general 1002 message Start date too large: {xxx}

1026 deprecated in favor of general 1002 message Date range too small: {xxx}

1027 deprecated in favor of general 1002 message Date range too large: {xxx}

2002 deprecated in favor of general 1002 message Missing resource: {xxx}

2003 deprecated in favor of general 1002 message Multiple resources invalid: {xxx}

2004 deprecated in favor of general 1002 message

Path incomplete: {xxx}