V9.ListingsService:GetProgramDetails

Jump to: navigation, search

GetProgramDetails

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:

  • Page
  • InProgress
  • Duration
  • SourceFilter
  • StartDate

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.

  • Image
  • ImageCount
  • ImageFormatIds

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 one page of upcoming broadcast data at a time.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.

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>
    <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 Example 1 »

Request information about the movie The Tourist.

Request Example 2 »

Request the broadcast schedule of Star Trek: Next Generation on my cable service over the next week.

Request Example 3 »

Request IDs, images, and awards for the cast and crew of the TV series House.

Request Example 4 »

Request information about the seasons of the TV series Castle in Spain.

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.

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:
CategoryCopy Type Fallback Sequence
Movie

1
4
55
54
3
5

Chrono Long
Chrono Short
Synopsis
Short Synopsis
No Cast
Grid

Series Master

3
55
54

No Cast
Synopsis
Short Synopsis

Series Episode

1
55
54
4
5

Chrono Long
Synopsis
Short Synopsis
Chrono Short
Grid

One Time Only

1
55
54
4
5

Chrono Long
Synopsis
Short Synopsis
Chrono Short
Grid

Season

36


38
39

Season description
— For select series and seasons
— For AMG season copy
Critical description
Season essay

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:
  • To get the best program images for a particular page, use any of the 12 image filters in the Image object. Create several combinations of filters and execute them in order of priority until you get the best images available for that page.
  • To get the images that work best for a page design, across all of your program pages, we recommend using the ImageFormatId image filter or the ImageFormatIds parameter.
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

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 GetProgramDetails

NameTypeDescription
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.

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>
    <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>

Error Codes

CodeNameDescription
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).

See Also

↑ Top

 
Personal tools