TvRest/V1/GridSchedule

Jump to: navigation, search

Listings/GridSchedule

Returns up to four hours of TV listings during the next two weeks with information that is designed for the space limitations of a grid. This request provides optional arguments to filter the list of channels returned.

When planning a TV listings grid, allow for listings that start at times other than on the hour and half-hour.

Syntax

listings/gridschedule/serviceid/info?apikey=apikey&sig=sig&locale=locale [&startdate=startdate] [&duration=duration] [&sourceid=sourceid] [&sourcefilterexclude=sourcefilterexclude] [&sourcefilterinclude=sourcefilterinclude] [&includechannelimages=includechannelimages] [&imageformatid=imageformatid] [&titletype=titletype] [&format=format]

Request Example 1

Request the next two hours of TV listings for Time Warner Cable in Beverly Hills.
http://api.rovicorp.com/TVlistings/v9/listings/gridschedule/360861/info?apikey=apikey&sig=sig&
locale=en-US&duration=120

Request Example 2

Include channel logos in the response.
http://api.rovicorp.com/TVlistings/v9/listings/gridschedule/360861/info?apikey=apikey&sig=sig&
locale=en-US&duration=120&includechannelimages=true

Request Example 3

Exclude Music and Pay-Per-View channels from the response.
http://api.rovicorp.com/TVlistings/v9/listings/gridschedule/360861/info?apikey=apikey&sig=sig&
locale=en-US&duration=120&sourcefilterexclude=PPV,Music

Request Example 4

Request TV listings with title type 1 starting at 8:00 pm for one hour and include channel logos.
http://api.rovicorp.com/TVlistings/v9/listings/gridschedule/360861/info?apikey=apikey&sig=sig&
locale=en-US&titletype=1&startdate=2011-04-18T20:00:00-08:00&duration=60&
includechannelimages=true

Request Parameters

Sort none.gif  Click to re-sort

Parameter Required Description
apikeyYesAccess code that authorizes your request for data from Rovi.
localeYesLanguage and country code of the television service. This is a case-sensitive combination of the ISO 639 language code, a hyphen character, and the ISO 3166 country code, as described in RFC 1766. Valid locales include:
  • da‑DK
Danish, Denmark
  • no‑NO
Norwegian, Norway
  • nl‑BE
Dutch, Belgium
  • pl‑PL
Polish, Poland
  • nl‑NL
Dutch, Netherlands
  • pt‑BR
Portuguese, Brazil
  • en‑BM
English (US), Bermuda
  • pt‑PT
Portuguese, Portugal
  • en‑CA
English (US), Canada
  • es‑AR
Spanish, Argentina
  • en‑IE
English (US), Ireland
  • es‑BO
Spanish, Bolivia
  • en‑JM
English (US), Jamaica
  • es‑CL
Spanish, Chile
  • en‑GB
English (UK), United Kingdom*
  • es‑CO
Spanish, Colombia
  • en‑US
English (US), United States
  • es‑CR
Spanish, Costa Rica
  • fi‑FI
Finnish, Finland
  • es‑DO
Spanish, Dominican Republic
  • fl‑BE
Flemish, Belgium
  • es‑EC
Spanish, Ecuador
  • fr‑BE
French, Belgium
  • es‑SV
Spanish, El Salvador
  • fr‑CA
French, Canada
  • es‑GT
Spanish, Guatemala
  • fr‑FR
French, France
  • es‑HN
Spanish, Honduras
  • fr‑LU
French, Luxembourg
  • es‑MX
Spanish, Mexico
  • fr‑CH
French, Switzerland
  • es‑NI
Spanish, Nicaragua
  • de‑AT
German, Austria
  • es‑PA
Spanish, Panama
  • de‑DE
German, Germany
  • es‑PE
Spanish, Peru
  • de‑LU
German, Luxembourg
  • es‑ES
Spanish, Spain
  • de‑CH
German, Switzerland
  • es‑US
Spanish, United States
  • it‑IT
Italian, Italy
  • es‑VE
Spanish, Venezuela
  • it‑CH
Italian, Switzerland
  • sv‑SE
Swedish, Sweden

* Includes Wales, Scotland, and Northern Ireland.

Note 1: Locale determines the language of program titles and descriptions. If content is not available in that language, a fallback language is chosen according to rules shown in the Language Fallback Sequence table.

Note 2: If an invalid locale is specified, en-GB will be used.

serviceidYesDatabase ID of the television service. You can get the service ID for a television service from responses to Listings/Services.
sigYesA calculated, 32-hex-digit authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three strings:
  • Your API key.
  • The secret key you received with your API key.
  • The Unix time. Unix time is a timestamp supported in most development environments, and is generally defined as the number of seconds since January 1, 1970 00:00:00 GMT.

Express the alpha hex digits as lower case.

Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time. If you're testing the call in a browser, use our online signature generator to perform the calculation.

durationNoNumber of minutes of program schedule to return, from 1 to 240 minutes (4 hours). Default is 1.

Note: The schedule is determined by duration and startdate. The start can be anytime from the time of the request up to two weeks in the future.

formatNoFormat of the returned data: json or xml. Default is json.
imageformatidNoIf you set includechannelimages to true, imageformatid determines the image format and maximum dimensions of the channel logos returned in the response. Choose the ID from the Format ID table.

Note: Logos may not be available in all format IDs.

includechannelimagesNoWhether to include channel logos in the response: true or false. Default is false.

Note:  Some channels do not have logos. For those channels, display call letters instead.

sourcefilterexcludeNoIf you specify sourceid to select the television sources to be returned, sourcefilterexclude specifies attributes of the channels in the source ID list that you want to eliminate from the channels returned.
  • HD
High-definition.
  • PPV
Pay-Per-View.
  • Music  
Music.
The values are case-sensitive. Specify multiple values as a comma-separated list, like this: sourcefilterexclude=HD,PPV. This request is mutually exclusive with sourcefilterinclude.
sourcefilterincludeNoIf you specify sourceid to select the television sources to be returned, sourcefilterinclude specifies attributes of the channels in the source ID list that you want to include in the channels returned.
  • HD
High-definition.
  • PPV
Pay-Per-View.
  • Music  
Music.
The values are case-sensitive. Specify multiple values as a comma-separated list, like this: sourcefilterinclude=HD,PPV. This request is mutually exclusive with sourcefilterexclude.
sourceidNoChannel sources to include on the schedule, specified as a comma-separated list like this: sourceid=423,1219,6191,8272,8274,8276,8277,8278,8279,8753,10335. You can get source IDs of channels from responses to a ServiceDetails request. Note: a single television source may supply content to multiple channels.

You can filter the source ID list further with either sourcefilterinclude or sourcefilterexclude.

startdateNoStart of the time period covered by the schedule, specified in a DateTime format. The schedule can be anytime from the time of the request to two weeks in the future. Default is the time of the request.

Note: The schedule is determined by startdate and duration.

titletypeNoType of title to return for each program. For a grid, you may want to limit title length to 15 characters (type 1) or 8 characters (type 3). The types of titles you can choose from are shown in the Title Type table.

Note: Titles are not available for all title types. If a program does not have the title type specified, a title is not returned.

Response

Response Header

ResponseTypeDescription
BuildStringSoftware build version of the API.
EndTimestampDateTimeTime the server finished processing the request.
ErrorsError [ ]Processing errors or warnings.
RequestIdString GUIDA generated value that identifies the request and response.
StatusStatusProcessing status, indicating whether the request was successfully processed.
TimeStampDateTimeTime the server started processing the request.

Response Body

ResponseTypeDescription
Duration Integer Number of minutes of schedule information requested.
GridChannels GridChannel [ ] The list of channels and the schedule of programs on each channel.
Locale String Language and country code of the response, as specified by the locale parameter in the request.
Name String Name of the television service in less than 50 characters.
ServiceId Integer Database ID of the television service.
StartDate DateTime Beginning of the time period covered by the returned data.
TimeZones TimeZoneInfoGrid [ ] UTC offset applicable to a television service and when the offset begins and ends. Television broadcast times are returned in UTC time, and you need to apply the offset to calculate the local time. UTC offsets change with daylight savings time.

JSON Response Example

The following shows the response for Request Example 4 above. The response has been edited to reduce the length and formatted with extra spaces and carriage returns to make it easy to read.

Requested with http://api.rovicorp.com/TVlistings/v9/listings/gridschedule/360861/info?apikey=apikey&sig=sig&
locale=en-US&titletype=1&startdate=2011-04-18T20:00:00-08:00&duration=60&
includechannelimages=true.

{
   "GridScheduleResult":{
      "Locale":"en-US",
      "ServiceId":"360861",
      "Name":"Beverly Hills - Time Warner Cable- Walnut/Diamond Bar",
      "StartDate":"2011-04-19T04:00:00Z",
      "Duration":"60",
      "RequestId":"2d09dcda-50f8-4fe0-9b07-d718f5c8c76b",
      "TimeStamp":"2011-04-18T22:31:33.854Z",
      "Status":"PNE",
      "Errors":"",
      "EndTimestamp":"2011-04-18T22:31:33.901Z",
      "Build":"CPS Phase v9 Build 9.5.1.8",
      "TimeZones":[
         {
            "StartDateTime":"2011-03-13T10:00:00Z",
            "EndDateTime":"2011-11-06T09:00:00Z",
            "Offset":"-420"
         }
      ],
      "GridChannels":[
            {
               "ServiceId":"360861",
               "SourceId":"696",
               "Order":"20448",
               "Channel":"2",
               "CallLetters":"KCBS",
               "DisplayName":"KCBS",
               "SourceLongName":"KCBS",
               "Type":"24-Hours",
               "SourceType":"Broadcast",
               "ParentNetworkId":"2",
               "IconAvailable":"true",
               "IsChannelOverride":"false",
               "ChannelSchedules":"",
               "SourceAttributeTypes":"",
               "Airings":[
                     {
                        "ProgramId":"18816508",
                        "SeriesId":"3899277",
                        "Title":"Two and/Half Mn",
                        "EpisodeTitle":"Dead from the Waist Down",
                        "AiringTime":"2011-04-19T04:00:00Z",
                        "Duration":"31",
                        "Color":"Color",
                        "AiringType":"Repeat",
                        "CC":"true",
                        "LetterBox":"false",
                        "Stereo":"true",
                        "HD":"false",
                        "SAP":"false",
                        "TVRating":"TV-14@DL",
                        "Dolby":"true",
                        "DSS":"false",
                        "HDLevel":"HD Level Unknown",
                        "DVS":"false",
                        "Category":"Other",
                        "Subcategory":"comedy",
                        "Sports":"false"
                     },
                     {
                        "ProgramId":"19266366",
                        "SeriesId":"16504753",
                        "Title":"Mike & Molly",
                        "EpisodeTitle":"Samuel Gets Fired",
                        "AiringTime":"2011-04-19T04:31:00Z",
                        "Duration":"29",
                        "Color":"Color",
                        "AiringType":"New",
                        "CC":"true",
                        "LetterBox":"false",
                        "Stereo":"true",
                        "HD":"false",
                        "SAP":"false",
                        "TVRating":"None",
                        "Dolby":"true",
                        "DSS":"false",
                        "HDLevel":"HD Level Unknown",
                        "DVS":"false",
                        "Category":"Other",
                        "Subcategory":"comedy",
                        "Sports":"false"
                     },
                     {
                        "ProgramId":"19238718",
                        "SeriesId":"15956802",
                        "Title":"Hawaii Five-0",
                        "EpisodeTitle":"Ho'opa'i",
                        "AiringTime":"2011-04-19T05:00:00Z",
                        "Duration":"60",
                        "Color":"Color",
                        "AiringType":"New",
                        "CC":"true",
                        "LetterBox":"false",
                        "Stereo":"true",
                        "HD":"false",
                        "SAP":"false",
                        "TVRating":"TV-14@V",
                        "Dolby":"true",
                        "DSS":"false",
                        "HDLevel":"HD Level Unknown",
                        "DVS":"false",
                        "Category":"Other",
                        "Subcategory":"crime drama",
                        "Sports":"false"
                     }
               ],
               "ChannelImages":[
                  {
                     "ImageUrl":"http:\/\/actual-url-concealed.jpg",
                     "ImageId":"39064",
                     "ImageTitle":"CBS",
                     "ImageCaption":"Source Logo",
                     "ObjectId":"696",
                     "ObjectName":"CBS; CBS",
                     "ImageCredit":"CBS",
                     "ImageCreditDisplay":"false",
                     "ImageType":"Station Logo",
                     "ImageHorizontalResolution":"64",
                     "ImageVerticalResolution":"64",
                     "ImageFormatId":"5",
                     "AspectRatio":"1:1",
                     "ImageOwner":"CBS",
                     "ParentImageId":"16786820",
                     "ObjectType":"Source",
                     "ImageFormat":"png",
                     "ImageExpiryDateTime":"",
                     "LastUpdate":"2009-02-05T10:13:15.79Z"
                  }
            ],
            {
               "ServiceId":"360861",
               "SourceId":"12013",
               "Order":"30449",
               "Channel":"3",
               "CallLetters":"TVGN",
               "DisplayName":"TVGN",
               "SourceLongName":"TV Guide Network (West)",
               "Type":"24-Hours",
               "SourceType":"Basic",
               "ParentNetworkId":"81",
               "IconAvailable":"true",
               "IsChannelOverride":"false",
               "ChannelSchedules":"",
               "SourceAttributeTypes":"",
               "Airings":[
                     {
                        "ProgramId":"18871817",
                        "Title":"Hollywood/Love",
                        "AiringTime":"2011-04-19T04:00:00Z",
                        "Duration":"60",
                        "Color":"Color",
                        "AiringType":"Repeat",
                        "CC":"true",
                        "LetterBox":"false",
                        "Stereo":"true",
                        "HD":"false",
                        "SAP":"false",
                        "TVRating":"TV-PG",
                        "Dolby":"false",
                        "DSS":"false",
                        "HDLevel":"HD Level Unknown",
                        "DVS":"false",
                        "Category":"Lifestyle",
                        "Subcategory":"entertainment",
                        "Sports":"false"
                     },
                     {
                        "ProgramId":"1137482",
                        "Title":"Diana/Hearts",
                        "AiringTime":"2011-04-19T05:00:00Z",
                        "Duration":"120",
                        "Color":"Color",
                        "AiringType":"Repeat",
                        "CC":"true",
                        "LetterBox":"false",
                        "Stereo":"true",
                        "HD":"false",
                        "SAP":"false",
                        "TVRating":"TV-PG",
                        "Dolby":"false",
                        "DSS":"false",
                        "HDLevel":"HD Level Unknown",
                        "DVS":"false",
                        "Category":"Other",
                        "Subcategory":"biography",
                        "Sports":"false"
                     }
               ],
               "ChannelImages":[
                  {
                     "ImageUrl":"http:\/\/actual-url-concealed.jpg",
                     "ImageId":"3109356",
                     "ImageTitle":"TV Guide Network",
                     "ImageCaption":"WOTV logo",
                     "ObjectId":"12013",
                     "ObjectName":"TV Guide Network (West)",
                     "ImageCreditDisplay":"false",
                     "ImageType":"Station Logo",
                     "ImageHorizontalResolution":"140",
                     "ImageVerticalResolution":"63",
                     "ImageFormatId":"37",
                     "AspectRatio":"20:9",
                     "ParentImageId":"16892753",
                     "ObjectType":"Source",
                     "ImageFormat":"jpg",
                     "ImageExpiryDateTime":"",
                     "LastUpdate":"2010-12-10T16:07:57.3Z"
                  }
              ]
          ]
      }
   }
}

XML Response Example

The following shows the same response data as the JSON example above, but adding the request parameters format=xml and titletype=3.

Requested with http://api.rovicorp.com/TVlistings/v9/listings/gridschedule/360861/info?apikey=apikey&sig=sig&
locale=en-US&titletype=1&startdate=2011-04-18T20:00:00-08:00&duration=60&
includechannelimages=true&titletype=3&format=xml.

<GetGridScheduleResult Locale="en-US" ServiceId="360861" Name="Beverly Hills - Time Warner Cable- Walnut/Diamond Bar" StartDate="2011-04-19T04:00:00Z" Duration="60">
   <RequestId>db788cb1-598e-4592-bfad-f1355d783ea0</RequestId>
   <TimeStamp>2011-04-18T22:16:32.901Z</TimeStamp>
   <Status>PNE</Status>
   <Errors>
   <EndTimestamp>2011-04-18T22:16:33.166Z</EndTimestamp>
   <Build>CPS Phase v9 Build 9.5.1.8</Build>
   <TimeZones>
      <TimeZoneInfoGrid StartDateTime="2011-03-13T10:00:00Z" EndDateTime="2011-11-06T09:00:00Z" Offset="-420"/>
   </TimeZones>
   <GridChannels>
      <GridChannel ServiceId="360861" SourceId="696" Order="20448" Channel="2" CallLetters="KCBS" DisplayName="KCBS" SourceLongName="KCBS" Type="24-Hours" SourceType="Broadcast" ParentNetworkId="2" IconAvailable="true" IsChannelOverride="false">
         <ChannelSchedules/>
         <SourceAttributeTypes/>
         <Airings>
            <GridAiring ProgramId="18816508" SeriesId="3899277" Title="Two/Half" EpisodeTitle="Dead from the Waist Down" AiringTime="2011-04-19T04:00:00Z" Duration="31" Color="Color" AiringType="Repeat" CC="true" LetterBox="false" Stereo="true" HD="false" SAP="false" TVRating="TV-14@DL" Dolby="true" DSS="false" HDLevel="HD Level Unknown" DVS="false" Category="Other" Subcategory="comedy" Sports="false"/>
            <GridAiring ProgramId="19266366" SeriesId="16504753" Title="Mike &amp; M" EpisodeTitle="Samuel Gets Fired" AiringTime="2011-04-19T04:31:00Z" Duration="29" Color="Color" AiringType="New" CC="true" LetterBox="false" Stereo="true" HD="false" SAP="false" TVRating="None" Dolby="true" DSS="false" HDLevel="HD Level Unknown" DVS="false" Category="Other" Subcategory="comedy" Sports="false"/>
            <GridAiring ProgramId="19238718" SeriesId="15956802" Title="Hawaii" EpisodeTitle="Ho'opa'i" AiringTime="2011-04-19T05:00:00Z" Duration="60" Color="Color" AiringType="New" CC="true" LetterBox="false" Stereo="true" HD="false" SAP="false" TVRating="TV-14@V" Dolby="true" DSS="false" HDLevel="HD Level Unknown" DVS="false" Category="Other" Subcategory="crime drama" Sports="false"/>
         </Airings>
         <ChannelImages>
            <ImageGrid ImageUrl="http://cps-static.macrovision.com/RichMediaAssets/Open/Images/39064_CBS.png?Partner=csqa@tvguide.com" ImageId="39064" ImageTitle="CBS" ImageCaption="Source Logo" ObjectId="696" ObjectName="CBS; CBS" ImageCredit="CBS" ImageCreditDisplay="false" ImageType="Station Logo" ImageHorizontalResolution="64" ImageVerticalResolution="64" ImageFormatId="5" AspectRatio="1:1" ImageOwner="CBS" ParentImageId="16786820">
               <ObjectType>Source</ObjectType>
               <ImageFormat>png</ImageFormat>
               <ImageExpiryDateTime xsi:nil="true"/>
               <LastUpdate>2009-02-05T10:13:15.79Z</LastUpdate>
            </ImageGrid>
         </ChannelImages>
      </GridChannel>
      <GridChannel ServiceId="360861" SourceId="12013" Order="30449" Channel="3" CallLetters="TVGN" DisplayName="TVGN" SourceLongName="TV Guide Network (West)" Type="24-Hours" SourceType="Basic" ParentNetworkId="81" IconAvailable="true" IsChannelOverride="false">
         <ChannelSchedules/>
         <SourceAttributeTypes/>
         <Airings>
            <GridAiring ProgramId="18871817" Title="Love" AiringTime="2011-04-19T04:00:00Z" Duration="60" Color="Color" AiringType="Repeat" CC="true" LetterBox="false" Stereo="true" HD="false" SAP="false" TVRating="TV-PG" Dolby="false" DSS="false" HDLevel="HD Level Unknown" DVS="false" Category="Lifestyle" Subcategory="entertainment" Sports="false"/>
            <GridAiring ProgramId="1137482" Title="Diana" AiringTime="2011-04-19T05:00:00Z" Duration="120" Color="Color" AiringType="Repeat" CC="true" LetterBox="false" Stereo="true" HD="false" SAP="false" TVRating="TV-PG" Dolby="false" DSS="false" HDLevel="HD Level Unknown" DVS="false" Category="Other" Subcategory="biography" Sports="false"/>
         </Airings>
         <ChannelImages>
            <ImageGrid ImageUrl="http://cps-static.macrovision.com/RichMediaAssets/Open/Images/3109356_TVGUIDENETWORK.jpg?Partner=csqa@tvguide.com" ImageId="3109356" ImageTitle="TV Guide Network" ImageCaption="WOTV logo" ObjectId="12013" ObjectName="TV Guide Network (West)" ImageCreditDisplay="false" ImageType="Station Logo" ImageHorizontalResolution="140" ImageVerticalResolution="63" ImageFormatId="37" AspectRatio="20:9" ParentImageId="16892753">
               <ObjectType>Source</ObjectType>
               <ImageFormat>jpg</ImageFormat>
               <ImageExpiryDateTime xsi:nil="true"/>
               <LastUpdate>2010-12-10T16:07:57.3Z</LastUpdate>
            </ImageGrid>
         </ChannelImages>
      </GridChannel>
   </GridChannels>
</GetGridScheduleResult>

Error Codes

CodeNameDescription
1001 Core_MandatoryFieldMissing A mandatory parameter is not specified.
10603 LookupService_InvalidLocale The locale specified in the request is invalid.
502000 Listings_TitleTypeOutOfRange The titletype specified in the request is invalid. This is a warning; the default value is used instead.

See Also

↑ Top

 
Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/TvRest/V1/GridSchedule"
Personal tools