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:
When planning a TV listings grid, allow for listings that start at times other than on the hour and half-hour.
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 the schedule for Time Warner Cable in Beverly Hills, California, over the next 60 minutes.
Request a schedule with channel logos for CanalSat in Paris, France, over the next 60 minutes.
Request the schedule for Time Warner in southern Manhattan starting on Thursday night at 8:00.
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.
Name | Required | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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:
[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:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | Type | Description |
---|---|---|
Build | String | Software build version of the API. |
ClientBatchId | String | The batch ID you supplied in the request. |
EndTimestamp | DateTime | Time the server finished processing the request. |
Errors | Error [ ] | Processing errors or warnings. |
RequestId | String GUID | A generated value that identifies the request and response. |
Status | Status | Processing status, indicating whether the request was successfully processed. |
TimeStamp | DateTime | Time the server started processing the request. |
Name | Type | Description |
---|---|---|
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. |
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>
Code | Name | Description |
---|---|---|
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. |