TvRest/V1/LinearSchedule

Jump to: navigation, search

Listings/LinearSchedule

Returns up to four hours of TV listings during the next two weeks with detailed program information. This request provides an optional argument to filter the list of channels returned.

This request returns compelling information not available on a grid schedule:

  • Program descriptions
  • Program images (to be added)
  • Showing types, which announce premieres and finales

Syntax

listings/linearschedule/serviceid/info?apikey=apikey&sig=sig&locale=locale [&duration=duration] [&inprogress=inprogress] [&oneairingpersourceid=oneairingpersourceid] [&sourceid=sourceid] [&startdate=startdate] [&format=format]

Request Example 1

Request the TV schedule for Time Warner Cable in Beverly Hills for the next half hour.
http://api.rovicorp.com/TVlistings/v9/listings/linearschedule/360861/info?locale=en-US&
duration=30&inprogress=true&apikey=apikey&sig=sig

Request Example 2

Find out what's up next on each channel.
http://api.rovicorp.com/TVlistings/v9/listings/linearschedule/360861/info?locale=en-US&
oneairingpersourceid=true&apikey=apikey&sig=sig

Request Example 3

Request a four-hour schedule starting at noon.
http://api.rovicorp.com/TVlistings/v9/listings/linearschedule/360861/info?locale=en-US&
duration=240&startdate=2011-03-02T20:00:00Z&apikey=apikey&sig=sig

Request Example 4

Request a schedule just for certain channels.
http://api.rovicorp.com/TVlistings/v9/listings/linearschedule/360861/info?locale=en-US&
duration=60&inprogress=true&sourceid=5,696,692,9169&apikey=apikey&sig=sig

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.

serviceidYesThe television service. You can return a list of service IDs offered to a community with a Listings/Services request.
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 the schedule will cover, from 1 to 240 (4 hours). The default is 1.

Note: The schedule is determined by duration, inprogress, 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.
inprogressNoWhether shows in progress at the time specified for startdate are included in the schedule: true or false. Default is false.
oneairingpersourceidNoWhether to return only the next show on each channel that is not in progress at the time specified by startdate: true or false. Default is false.

Note: Setting this parameter to true overrides the inprogress and duration parameters.

sourceidNoThe channel or channels that will appear on the schedule. You can get the source IDs for channels from responses to Listings/ServiceDetails requests.

To specify multiple channels, specify a comma-separated list, like this: sourceid=696,873,5,994.

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, duration, and inprogress.

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
Schedule LinearSchedule The schedule of programs on each channel.

JSON Response Example

Here's the response to Request Example 1, which asks for the TV schedule for Time Warner Cable in Beverly Hills for the next 30 minutes. 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/linearschedule/360861/info?locale=en-US&
duration=30&inprogress=true&apikey=apikey&sig=sig.

{
   "LinearScheduleResult":{
      "RequestId":"275fb089-c483-41c1-b987-d6138374d008",
      "TimeStamp":"2011-03-02T01:15:17.139Z",
      "Status":"PNE",
      "Errors":"",
      "EndTimestamp":"2011-03-02T01:15:17.139Z",
      "Build":"9.4.0.0",
      "Schedule":{
         "Locale":"en-US",
         "ServiceId":"360861",
         "Name":"Beverly Hills - Time Warner",
         "ServiceType":"Cable",
         "StartDate":"2011-03-01T23:00:00Z",
         "Duration":"30",
         "TimeZones":[
            (
               "StartDateTime":"2010-11-07T09:00:00Z",
               "EndDateTime":"2011-03-13T10:00:00Z",
               "Offset":"-480"
            }
         ],
         "Airings":[
               {
                  "ProgramId":"19131002",
                  "SeriesId":"21985",
                  "InstanceId":"",
                  "UnknownInstance":"false",
                  "UPId":"autofill",
                  "Title":"Judge Judy",
                  "Copy":"Ownership of a dog is disputed.",
                  "AiringTime":"2011-03-01T23:00:00Z",
                  "Duration":"30",
                  "Color":"Color",
                  "AiringType":"New",
                  "ShowingType":"Unknown",
                  "CC":"true",
                  "LetterBox":"false",
                  "Stereo":"true",
                  "HD":"false",
                  "SAP":"false",
                  "TVRating":"TV-G",
                  "Dolby":"false",
                  "DSS":"false",
                  "HDLevel":"HD Level Unknown",
                  "Sports":"false",
                  "DVS":"false",
                  "Category":"Other",
                  "Subcategory":"reality",
                  "SourceId":"696",
                  "Channel":"2",
                  "CallLetters":"KCBS",
                  "SourceDisplayName":"KCBS",
                  "SourceLongName":"KCBS",
                  "TiVoSupported":"true",
                  "ParentNetworkId":"2",
                  "IconAvailable":"true",
                  "ServiceId":"360861",
                  "SL": "false",
                  "Subtitles": "false"
               },
               {
                  "ProgramId":"19067344",
                  "SeriesId":"3513",
                  "InstanceId":"",
                  "UnknownInstance":"false",
                  "UPId":"autofill",
                  "Title":"Oprah Winfrey",
                  "EpisodeTitle":"Willow Smith 'Whips Her Hair' & Oprah's All-Time Smartest, Most Talented Kids",
                  "Copy":"Willow Smith performs \"Whip My Hair\" and her new single, \"21st Century Girl\" on a show featuring talented youngsters. Also: Lenny Kravitz and a teen guitarist; Also: \"Live to Dance\" winners D'Angelo Castro and Amanda Carbajales; YouTube star Maya Sadler.",
                  "AiringTime":"2011-03-01T23:00:00Z",
                  "Duration":"60",
                  "Color":"Color",
                  "AiringType":"New",
                  "ShowingType":"Unknown",
                  "CC":"true",
                  "LetterBox":"false",
                  "Stereo":"true",
                  "HD":"false",
                  "SAP":"false",
                  "TVRating":"TV-PG",
                  "Dolby":"false",
                  "DSS":"false",
                  "HDLevel":"HD Level Unknown",
                  "Sports":"false",
                  "DVS":"false",
                  "Category":"Other",
                  "Subcategory":"talk",
                  "SourceId":"5",
                  "Channel":"7",
                  "CallLetters":"KABC",
                  "SourceDisplayName":"KABC",
                  "SourceLongName":"KABC",
                  "TiVoSupported":"true",
                  "ParentNetworkId":"1",
                  "IconAvailable":"true",
                  "ServiceId":"360861",
                  "SL": "false",
                  "Subtitles": "false"
               },
               {
                  "ProgramId":"5794639",
                  "InstanceId":"",
                  "UnknownInstance":"false",
                  "UPId":"rivins",
                  "Title":"Dragon Sword",
                  "Copy":"A weary knight (James Purefoy) embarks on a search for a missing princess in England.",
                  "AiringTime":"2011-03-01T22:00:00Z",
                  "Duration":"120",
                  "Color":"Color",
                  "AiringType":"Unknown",
                  "ShowingType":"Unknown",
                  "CC":"true",
                  "LetterBox":"false",
                  "Stereo":"false",
                  "HD":"false",
                  "SAP":"false",
                  "TVRating":"TV-PG@V",
                  "MovieRating":"NR",
                  "Dolby":"false",
                  "DSS":"false",
                  "HDLevel":"HD Level Unknown",
                  "Sports":"false",
                  "DVS":"false",
                  "Category":"Movie",
                  "Subcategory":"fantasy",
                  "SourceId":"9196",
                  "Channel":"59",
                  "CallLetters":"Syfy",
                  "SourceDisplayName":"SYFY-W",
                  "SourceLongName":"Syfy (West)",
                  "TiVoSupported":"true",
                  "ParentNetworkId":"37",
                  "IconAvailable":"true",
                  "ServiceId":"360861",
                  "SL": "false",
                  "Subtitles": "false"
               }
            ]
         }
      }
   }

Error Codes

CodeNameDescription
1001 Core_MandatoryFieldMissing A mandatory parameter is not specified.
10603 LookupService_InvalidLocale The locale specified in the request is invalid.

See Also

↑ Top

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