Note: The information returned by this request is also returned by requests offered in our Video API Version 1.1. Because future API development around this information will be focused on the Video API, we now recommend using the Video API for future application development instead of this request.
GetProgramDetails returns information about a series, movie, episode, or program, and can optionally include a schedule of upcoming broadcasts of the show.
To include a schedule of upcoming broadcasts, specify ServiceId and then limit and format the results with the following parameters:
|
|
|
|
|
To return program images, specify Images in the MetaData parameter and then select and filter the results with the following parameters. Note: These parameters filter images for the program, not images returned with program credits.
| |
| |
|
This request returns a large amount of data. To speed data transmission, do the following:
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>
<GetProgramDetails xmlns="http://api.rovicorp.com/v9/listings">
<request>
<Locale>string</Locale>
<MetaData>
<ProgramMetaData>All or None or Program or Credit or Keyword or Image or Award or SeasonWithEpisodes or SeasonWithoutEpisodes or Video or UnsequencedEpisodes or ProgramVariants</ProgramMetaData>
<ProgramMetaData>All or None or Program or Credit or Keyword or Image or Award or SeasonWithEpisodes or SeasonWithoutEpisodes or Video or UnsequencedEpisodes or ProgramVariants</ProgramMetaData>
</MetaData>
<Format>PlainText or HTML</Format>
<ServiceId>int</ServiceId>
<StartDate>dateTime</StartDate>
<Duration>int</Duration>
<InProgress>boolean</InProgress>
<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>
<TitleType>int</TitleType>
<CopyType>int</CopyType>
<Image>
<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>
<MaxImageScale>float</MaxImageScale>
</Image>
<Page>
<PageSize>int</PageSize>
<StartIndex>int</StartIndex>
<TotalRows>int</TotalRows>
<SortByColumn>
<int>int</int>
<int>int</int>
</SortByColumn>
</Page>
<FilterAdultContents>boolean</FilterAdultContents>
<UnsequencedEpisodePage>
<PageSize>int</PageSize>
<StartIndex>int</StartIndex>
<TotalRows>int</TotalRows>
<SortByColumn>
<int>int</int>
<int>int</int>
</SortByColumn>
</UnsequencedEpisodePage>
<FilterCopyTextSource>int</FilterCopyTextSource>
<ContentProviderIds>
<int>int</int>
<int>int</int>
</ContentProviderIds>
<ImageCount>int</ImageCount>
<ImageFormatIds>
<int>int</int>
<int>int</int>
</ImageFormatIds>
<FallbackLocales>string</FallbackLocales>
<SpecifiedProgramData>boolean</SpecifiedProgramData>
</request>
</GetProgramDetails>
</soap12:Body>
</soap12:Envelope>
Request information about the movie The Tourist.
Request the broadcast schedule of Star Trek: Next Generation on my cable service over the next week.
Request IDs, images, and awards for the cast and crew of the TV series House.
Request information about the seasons of the TV series Castle in Spain.
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
MetaData | Yes | ProgramMetaData [ ] | The program information you want to include in the results. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ProgramHandle | Yes | Handle | Identifier for the program or series you want information about. You can get the program ID for Handle from responses to the following requests: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ContentProviderIds | Unsupported | Integer [ ] | This parameter is restricted to custom Rovi applications. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CopyType | No | Nullable CopyType | Type of description you want. If you specify a copy type that has no content, no description is returned. If you specify 0 or no copy type, the description chosen is based on category, shown below, and the first copy type in the category that is available:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Duration | No | Nullable Integer | If you specify a ServiceId to include upcoming broadcasts, Duration determines the number of minutes the schedule will cover. You can specify 1 to 20160; the default is 20160 (14 days).
Note: The schedule is determined by StartDate, Duration, and InProgress. A duration shorter than 5 minutes may miss shows starting just before or after a half-hour point. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FallbackLocales | No | String | Sequence of locales, in a comma-separated list, to use if program titles and descriptions are not available in the language specified by the Locale parameter. For example: "fr-CA,es-ES,en-GB,en-US". Titles and descriptions will be returned only for those languages.
This sequence overrides the default fallback specified in the Language Fallback Sequence table | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FilterAdultContents | No | Nullable Boolean | Whether to filter cast and crew members that are tagged as Adult. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FilterCopyTextSource | No | Nullable Integer | ID of the source of the copy text you want. Copy text source IDs are returned, if available, in a CopyTextSource element in Program, CelebrityCredit, and ListingsAiring objects. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Format | No | Nullable EncodingFormat | Encoding format of the returned program description: HTML or PlainText. Default is PlainText. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Image | No | Image | If you specify Images or All in the MetaData parameter, Image determines which program images are returned in the ProgramImages object. Do one of the following:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ImageCount | No | Nullable Integer | Number of program images to be returned if you specify Images or All in the MetaData parameter. Default is 5. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ImageFormatIds | No | Integer [ ] | If you specify Images or All in the MetaData parameter, ImageFormatIds determines the image formats and maximum dimensions of the program images returned in the ProgramImages object. Select the IDs from the Format IDs table. Images are not available in all format IDs, however, and images cannot be filtered by Image Format ID 0.
Note: This parameter supplements any filters specified in the Image parameter. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
InProgress | No | Nullable Boolean | If you specify a ServiceId to include upcoming broadcasts, InProgress determines whether shows that are in progress at StartDate are included in the results: true or false. Default is false.
Note: The upcoming schedule is determined by StartDate, Duration, and InProgress. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Page | No | DataPage | If you specify a ServiceId to include upcoming broadcasts, you can use Page to determine the sequence of the listings and to return listings one pageful at a time. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ServiceId | No | Nullable Integer | The channel lineup the program airs on. This must be specified if you want to return a schedule of upcoming broadcasts of the show. You can return a list of service IDs offered to a community with GetServices. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SourceFilter | No | SourceFilter | If you specify a ServiceId to include a schedule of upcoming broadcasts, you can use SourceFilter to limit the channels that are included in the results. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SpecifiedProgramData | No | Nullable Boolean | Whether a variant program ID specified in the ProgramHandle object should be used instead of the primary program ID associated with that variant: true or false. Default is false, the primary program ID will be used instead.
A program may have multiple IDs, each of which is categorized as primary or variant. Variants differ in some way from the primary, such as titles, format, content, language, or cast (for animated shows). A program may, however, have multiple primary IDs, such as for different languages. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
StartDate | No | Nullable DateTime | If you specify a ServiceId to include upcoming broadcasts, you can use StartDate to specify the starting time of the schedule. The default is the time of the request.
Note: The schedule is determined by StartDate, Duration, and InProgress. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TitleType | No | Nullable TitleType | Type of title to return for each program. Most programs do not carry all title types, so we recommend using the default unless another type is required. If a program does not have the type specified, the Title element is not returned. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TVObjectId | Unsupported | Integer | This parameter has been deprecated. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
UnsequencedEpisodePage | Unsupported | DataPage | This parameter is restricted to custom Rovi applications. |
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 |
---|---|---|
Page | DataPage | The number of upcoming broadcasts available, plus echoes of the parameters specified in the Page parameter. |
Program | Program | Information about the program. |
Schedule | LinearSchedule | The requested upcoming broadcasts of the program. |
UnsequencedEpisodePage | DataPage | The number of unsequenced episodes available, and echoes of the parameters specified in the UnsequencedEpisodePage object. |
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>
<GetProgramDetailsResponse xmlns="http://api.rovicorp.com/v9/listings">
<GetProgramDetailsResult>
<Program DataAvailabilityFlags="int">
<ProgramHandle>
<Id>string</Id>
<ProviderId>int</ProviderId>
</ProgramHandle>
<SeriesId>string</SeriesId>
<TvObjectId>int</TvObjectId>
<MasterTitle>string</MasterTitle>
<EpisodeTitle>string</EpisodeTitle>
<CopyText>string</CopyText>
<Runtime>int</Runtime>
<ProgramType>string</ProgramType>
<Category>string</Category>
<Subcategory>string</Subcategory>
<ReleaseYear>int</ReleaseYear>
<Season>string</Season>
<EpisodeNumber>string</EpisodeNumber>
<PartNumber>int</PartNumber>
<PartTotal>int</PartTotal>
<StarRating>int</StarRating>
<TVRating>string</TVRating>
<MovieRating>string</MovieRating>
<Subtitled>boolean</Subtitled>
<Letterbox>boolean</Letterbox>
<CC>boolean</CC>
<Color>string</Color>
<OriginalAirDate>dateTime</OriginalAirDate>
<Syndicated>boolean</Syndicated>
<Keywords>
<string>string</string>
<string>string</string>
</Keywords>
<Credits>
<ProgramCredit xsi:nil="true" />
<ProgramCredit xsi:nil="true" />
</Credits>
<ProgramImages>
<Image xsi:nil="true" />
<Image xsi:nil="true" />
</ProgramImages>
<IsVideoAvailable>boolean</IsVideoAvailable>
<SeasonSequence>int</SeasonSequence>
<SeriesSequence>int</SeriesSequence>
<LastAirDate>dateTime</LastAirDate>
<CuttingPositions>
<int>int</int>
<int>int</int>
</CuttingPositions>
<ParentalRatings>
<ParentalRating xsi:nil="true" />
<ParentalRating xsi:nil="true" />
</ParentalRatings>
<ProgramVariants>
<ProgramVariant xsi:nil="true" />
<ProgramVariant xsi:nil="true" />
</ProgramVariants>
<ProgramVideoClips>
<VideoClip xsi:nil="true" />
<VideoClip xsi:nil="true" />
</ProgramVideoClips>
<ProgramAwards>
<Award xsi:nil="true" />
<Award xsi:nil="true" />
</ProgramAwards>
<ProgramLanguage>string</ProgramLanguage>
<CopyTextLanguage>string</CopyTextLanguage>
<ShowSeasons>
<TVSeason xsi:nil="true" />
<TVSeason xsi:nil="true" />
</ShowSeasons>
<SubtitleLanguage>string</SubtitleLanguage>
<SecondaryTitle>string</SecondaryTitle>
<UnsequencedEpisodes>
<Program xsi:nil="true" />
<Program xsi:nil="true" />
</UnsequencedEpisodes>
<CopyTextSource SourceId="int" SourceName="string" />
<Streamable>int</Streamable>
</Program>
<Schedule>
<Locale>string</Locale>
<ServiceId>int</ServiceId>
<Name>string</Name>
<ServiceType>string</ServiceType>
<StartDate>dateTime</StartDate>
<Duration>int</Duration>
<TimeZones>
<TimeZoneInfo xsi:nil="true" />
<TimeZoneInfo xsi:nil="true" />
</TimeZones>
<Airings>
<ListingsAiring xsi:nil="true" />
<ListingsAiring xsi:nil="true" />
</Airings>
</Schedule>
<Page>
<PageSize>int</PageSize>
<StartIndex>int</StartIndex>
<TotalRows>int</TotalRows>
<SortByColumn>
<int>int</int>
<int>int</int>
</SortByColumn>
</Page>
<UnsequencedEpisodePage>
<PageSize>int</PageSize>
<StartIndex>int</StartIndex>
<TotalRows>int</TotalRows>
<SortByColumn>
<int>int</int>
<int>int</int>
</SortByColumn>
</UnsequencedEpisodePage>
</GetProgramDetailsResult>
</GetProgramDetailsResponse>
</soap12:Body>
</soap12:Envelope>
Code | Name | Description |
---|---|---|
1001 | Core_MandatoryFieldMissing | A mandatory parameter is not specified. |
5001 | Core_InvalidPagingStartIndex | The StartIndex specified for the Page parameter is negative, non-numeric, or results in a negative range. |
5002 | Core_InvalidPagingPageSize | The PageSize specified for Page parameter is negative or non-numeric. |
502001 | Listings_InvalidCopyType | The CopyType specified in the request is invalid. |
502002 | NoPrimaryProgramVariantExists | Warning: No primary program variant exists. Normally the data from the primary program ID is returned (unless you set SpecifiedProgramData to true), however this program has no primary program ID.
A program may have multiple IDs, each of which is categorized as primary or variant. Variants differ in some way from the primary, such as title, format, content, language, or cast (for animated shows). |