V9.ListingsService:GetGridSchedule

Jump to: navigation, search

GetGridSchedule

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, which enables you to offer customized schedules.

This request returns a large amount of data. To speed data transmission, do the following:

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.

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

Syntax

The following is a sample SOAP 1.2 request with placeholders. Your application development environment needs to replace the placeholders with actual values.
POST /v9/listingsservice.asmx HTTP/1.1
Host: api.rovicorp.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Header>
    <AuthHeader xmlns="http://api.rovicorp.com/v9/common/types">
      <UserName>string</UserName>
      <Password>string</Password>
    </AuthHeader>
  </soap12:Header>
  <soap12:Body>
    <GetGridSchedule xmlns="http://api.rovicorp.com/v9/listings">
      <request>
        <Locale>string</Locale>
        <ServiceId>int</ServiceId>
        <StartDate>dateTime</StartDate>
        <Duration>int</Duration>
        <TitleType>int</TitleType>
        <SourceFilter>
          <Sources>
            <SourceId>int</SourceId>
            <SourceId>int</SourceId>
          </Sources>
          <Include>HD or PPV or Music</Include>
          <Excludes>
            <Exclude>HD or PPV or Music</Exclude>
            <Exclude>HD or PPV or Music</Exclude>
          </Excludes>
        </SourceFilter>
        <IncludeChannelImages>boolean</IncludeChannelImages>
        <ImageFilter>
          <ImageUrl>string</ImageUrl>
          <ImageUseType>Logo or HeroImage or Thumbnail</ImageUseType>
          <ImageId>int</ImageId>
          <ImageTitle>string</ImageTitle>
          <ImageCaption>string</ImageCaption>
          <ObjectId>string</ObjectId>
          <ObjectType>Program or Credit or Source</ObjectType>
          <ObjectName>string</ObjectName>
          <Relevancy>boolean</Relevancy>
          <ImageCredit>string</ImageCredit>
          <ImageCreditDisplay>boolean</ImageCreditDisplay>
          <ImageCastWeight>float</ImageCastWeight>
          <ImageZoomLevel>1 or 2 or 3 or 4 or 5</ImageZoomLevel>
          <ImageHeadcount>int</ImageHeadcount>
          <ImageType>string</ImageType>
          <ImageFormat>jpg or png or gif or bmp</ImageFormat>
          <ImageHorizontalResolution>int</ImageHorizontalResolution>
          <ImageVerticalResolution>int</ImageVerticalResolution>
          <ImageMaintainAspectFlag>boolean</ImageMaintainAspectFlag>
          <ImageExpiryDateTime>dateTime</ImageExpiryDateTime>
          <LastUpdate>dateTime</LastUpdate>
          <ImageFormatId>int</ImageFormatId>
          <Orientation>string</Orientation>
          <AspectRatio>string</AspectRatio>
          <ImageOwner>string</ImageOwner>
          <ParentImageId>int</ParentImageId>
          <ProgramTitle>string</ProgramTitle>
          <MaxImageScale>float</MaxImageScale>
        </ImageFilter>
        <ChannelImageCount>int</ChannelImageCount>
      </request>
    </GetGridSchedule>
  </soap12:Body>
</soap12:Envelope>

Request Example 1 »

Request the schedule for Time Warner Cable in Beverly Hills, California, over the next 60 minutes.

Request Example 2 »

Request a schedule with channel logos for CanalSat in Paris, France, over the next 60 minutes.

Request Example 3 »

Request the schedule for Time Warner in southern Manhattan starting on Thursday night at 8:00.

Request Example 4 »

Request a schedule starting at 8:00 PM for the sports stations on Time Warner in southern Manhattan, except for the Pay-Per-View stations.

Request Parameters

NameRequiredTypeDescription
Locale Yes String Language and country code of the television service. This is a case-insensitive 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
  • nl-BE
Dutch, Belgium
  • nl-NL
Dutch, Netherlands
  • en-BM
English (US), Bermuda
  • en-CA
English (US), Canada
  • en-IE
English (US), Ireland
  • en-JM
English (US), Jamaica
  • en-GB
English (UK), United Kingdom[1]
  • en-US
English (US), United States
  • fi-FI
Finnish, Finland
  • fl-BE
Flemish, Belgium
  • fr-BE
French, Belgium
  • fr-CA
French, Canada
  • fr-FR
French, France
  • fr-LU
French, Luxembourg
  • fr-CH
French, Switzerland
  • de-AT
German, Austria
  • de-DE
German, Germany
  • de-LU
German, Luxembourg
  • de-CH
German, Switzerland
  • it-IT
Italian, Italy
  • it-CH
Italian, Switzerland
  • no-NO
Norwegian, Norway
  • pl-PL
Polish, Poland
  • pt-BR
Portuguese, Brazil
  • pt-PT
Portuguese, Portugal
  • es-AR
Spanish, Argentina
  • es-BO
Spanish, Bolivia
  • es-CL
Spanish, Chile
  • es-CO
Spanish, Colombia
  • es-CR
Spanish, Costa Rica
  • es-DO
Spanish, Dominican Republic
  • es-EC
Spanish, Ecuador
  • es-SV
Spanish, El Salvador
  • es-GT
Spanish, Guatemala
  • es-HN
Spanish, Honduras
  • es-MX
Spanish, Mexico
  • es-NI
Spanish, Nicaragua
  • es-PA
Spanish, Panama
  • es-PE
Spanish, Peru
  • es-ES
Spanish, Spain
  • es-US
Spanish, United States
  • es-VE
Spanish, Venezuela
  • sv-SE
Swedish, Sweden

[1] 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.

ServiceId Yes Integer Database ID of the television service. To get the service ID for the television service, request the list of services in the area with GetServices.
ChannelImageCount No Nullable Integer If IncludeChannelImages is set to true, number of logos to return per channel. Default is 1.
ClientBatchId No String A trace code to be returned in the response header so you can track a batch of requests. The code can be up to 255 characters.
Duration No Nullable Integer Number of minutes of schedule information to be returned, from 1 to 240 (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. A duration shorter than 5 minutes may miss shows starting just before or after a half-hour point.

ImageFilter No Image If IncludeChannelImages is set to true, ImageFilter specifies properties of the channel logos. Do one of the following:
  • To specify logos by maximum width and height, specify any ImageFormatId in the Logo category except for 0 and 2. Because most logos have a landscape orientation, however, we recommend using ImageFormatIds that have a width greater than the height.
  • To specify small color logos with a transparent background, specify a horizontal and vertical resolution of 92 x 36. Use a background with no white over 248 and no black under 20.
  • To specify black or white logos with a transparent background, specify a horizontal and vertical resolution of 122 x 66 and a ChannelImageCount of 2. From the results, parse the links to the images and choose which one you want, the black or white.
  • To specify logos with a transparent background that are visible on either light or dark backgrounds, specify a horizontal and vertical resolution of 2400 x 2400 and a ChannelImageCount of 5. From the results, parse the links to the five images and choose which one you want:
    • White — appropriate for a dark background
    • Grayscale — appropriate for a light or dark background
    • Color Dark — color logo appropriate for dark background
    • Color Light — color logo appropriate for a light background
    • Color Dark/Light — color logo appropriate for a light or dark background
IncludeChannelImages No Nullable Boolean Whether 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.

SourceFilter No SourceFilter Filter for the channels that are returned in the response.
StartDate No Nullable DateTime Start of the time period covered by the schedule, which 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.

TitleType No Nullable TitleType Type 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). 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.
ClientBatchIdStringThe batch ID you supplied in the request.
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 for GetGridSchedule

NameTypeDescription
Duration Integer Number of minutes of schedule information requested.
GridChannels GridChannel [ ] The channels requested and the programs broadcast on those channels during the time requested.
Locale String Language and country code of the response, as specified by Locale 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.

Response Example

The following is a sample SOAP 1.2 response with placeholders that show the type of content returned in an actual response.
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <GetGridScheduleResponse xmlns="http://api.rovicorp.com/v9/listings">
      <GetGridScheduleResult Locale="string" ServiceId="int" Name="string" StartDate="dateTime" Duration="int">
        <TimeZones>
          <TimeZoneInfoGrid StartDateTime="dateTime" EndDateTime="dateTime" Offset="int" />
          <TimeZoneInfoGrid StartDateTime="dateTime" EndDateTime="dateTime" Offset="int" />
        </TimeZones>
        <GridChannels>
          <GridChannel ServiceId="int" SourceId="int" Order="long" Channel="string" CallLetters="string" DisplayName="string" SourceLongName="string" Type="24-Hours or Partial or Shared" SourceType="PPV or Premium or LO or Basic or Broadcast or Blend or VOD or Network" ParentNetworkId="int" IconAvailable="boolean" IsChannelOverride="boolean">
            <ChannelSchedules xsi:nil="true" />
            <SourceAttributeTypes xsi:nil="true" />
            <Airings xsi:nil="true" />
            <ChannelImages xsi:nil="true" />
          </GridChannel>
          <GridChannel ServiceId="int" SourceId="int" Order="long" Channel="string" CallLetters="string" DisplayName="string" SourceLongName="string" Type="24-Hours or Partial or Shared" SourceType="PPV or Premium or LO or Basic or Broadcast or Blend or VOD or Network" ParentNetworkId="int" IconAvailable="boolean" IsChannelOverride="boolean">
            <ChannelSchedules xsi:nil="true" />
            <SourceAttributeTypes xsi:nil="true" />
            <Airings xsi:nil="true" />
            <ChannelImages xsi:nil="true" />
          </GridChannel>
        </GridChannels>
      </GetGridScheduleResult>
    </GetGridScheduleResponse>
  </soap12:Body>
</soap12:Envelope>

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.


↑ Top

 
Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/V9.ListingsService:GetGridSchedule"
Personal tools