V9.ListingsService:GetServiceDetails

Jump to: navigation, search

GetServiceDetails

Returns the channel lineup offered by a television service, the channels that broadcast on the service anytime during the next two weeks.

This request returns a large amount of data. To speed data transmission, request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.

This request requires the service ID of the television service. You can get service IDs from responses to a GetServices request.

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>
    <GetServiceDetails xmlns="http://api.rovicorp.com/v9/listings">
      <request>
        <Locale>string</Locale>
        <ServiceId>int</ServiceId>
        <StartDate>dateTime</StartDate>
        <Duration>int</Duration>
        <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>
          <MaxImageScale>float</MaxImageScale>
        </ImageFilter>
        <ImageCount>int</ImageCount>
      </request>
    </GetServiceDetails>
  </soap12:Body>
</soap12:Envelope>

Request Example 1 »

Request the channel lineup for Time Warner Cable in Beverly Hills, California.

Request Example 2 »

Request the channel lineup for Los Angeles area broadcast channels in Pasadena, California, along with small channel logos.

Request Example 3 »

Request the channel lineup for Shaw Cable in Moose Jaw, Saskatchewan, and the UTC offsets for the next six months.

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.

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.
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 that returned UTC offset information should cover, from 1 to 527040 (1 year). Default is 20160 (14 days).

You use UTC offset information to calculate local program times (program times returned are UTC time). Because UTC offsets change with daylight saving time, the response gives the start and end points of the UTC offsets that apply during the period covered by Duration and StartDate.

ImageCount No Nullable Integer If IncludeChannelImages is set to true, ImageCount specifies the maximum number of channel logos returned. The default is 1.
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 an ImageCount 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 an ImageCount 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.

StartDate No Nullable DateTime Starting point of the returned UTC offset information. Default is the time of the request.

You use UTC offset information to calculate local program times (program times are UTC time). Because UTC offsets change with daylight saving time, the response gives the start and end points of the UTC offsets that apply during the period covered by Duration and StartDate.

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 GetServiceDetails

NameTypeDescription
ChannelLineup ChannelLineup Information about the television service and the channels provided by the service.

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>
    <GetServiceDetailsResponse xmlns="http://api.rovicorp.com/v9/listings">
      <GetServiceDetailsResult>
        <ChannelLineup>
          <Channels>
            <ListingsChannel xsi:nil="true" />
            <ListingsChannel xsi:nil="true" />
          </Channels>
        </ChannelLineup>
      </GetServiceDetailsResult>
    </GetServiceDetailsResponse>
  </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.

See Also

↑ Top

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