TvRest/V1/ServiceDetails

Jump to: navigation, search

Listings/ServiceDetails

Returns the channel lineup offered by a television service, plus information about the source of programming on a channel.

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

Syntax

listings/servicedetails/serviceid/serviceid/info?apikey=apikey&sig=sig&locale=locale [&includechannelimages=includechannelimages] [&imageformatid=imageformatid] [&imagehorizontalresolution=imagehorizontalresolution] [&imageverticalresolution=imageverticalresolution] [&format=format]

Request Example 1

Request the channel lineup for Los Angeles Area broadcast channels.

Request Example 2

Request channel logos in the channel lineup.

Request Example 3

Request channel JPG logos in the channel lineup that fit a 500 x 500 pixel box.

Request Parameters

Sort none.gif  Click to re-sort

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

* Includes Wales, Scotland, and Northern Ireland.

serviceidYesService ID of the television service. To get the service ID for the television service, request the list of services in the area with Listings/Services.
sigYesA calculated, 32-hex-digit authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three strings:
  • Your API key.
  • The secret key you received with your API key.
  • The Unix time. Unix time is a timestamp supported in most development environments, and is generally defined as the number of seconds since January 1, 1970 00:00:00 GMT.

Express the alpha hex digits as lower case.

Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time. If you're testing the call in a browser, use our online signature generator to perform the calculation.

formatNoFormat of the returned data: json or xml. Default is json.
imageformatidNoIf you set includechannelimages to true, imageformatid determines the size and file format of channel logos returned in the response. Choose the ID from the Format ID table.

Note: Logos may not be available in all format IDs, and logos returned meet all of the image filters specified in the request:

  • imageformatid
  • imageverticalresolution
  • imagehorizontalresolution
imagehorizontalresolutionNoIf you set includechannelimages to true, imagehorizontalresolution determines the exact horizontal resolution of the images returned in the response (in pixels). To return images within a particular bounding box, use the imageformatid parameter instead.

Note: Logos may not be available in all resolutions, and logos returned meet all of the image filters specified in the request:

  • imageformatid
  • imageverticalresolution
  • imagehorizontalresolution
imageverticalresolutionNoIf you set includechannelimages to true, imageverticalresolution determines the exact vertical resolution of the images returned in the response (in pixels). To return images within a particular bounding box, use the imageformatid parameter instead.

Note: Logos may not be available in all resolutions, and logos returned meet all of the image filters specified in the request:

  • imageformatid
  • imageverticalresolution
  • imagehorizontalresolution
includechannelimagesNoWhether 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.

Response

Response Header

ResponseTypeDescription
BuildStringSoftware build version of the API.
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 Body

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

JSON Response Example

Here's the response to Request Example 1, which asks for the channel lineup for Los Angeles Area broadcast channels. The response has been edited to reduce the length and formatted with extra spaces and carriage returns to make it easy to read.

Requested with http://api.rovicorp.com/TVlistings/v9/listings/servicedetails/serviceid/20494/info?locale=en-US&
apikey=apikey&sig=sig
.

{
   "ServiceDetailsResult":{
      "RequestId":"13fb3f4b-d801-4c3c-a9e5-908757678074",
      "TimeStamp":"2011-09-09T23:31:53.102Z",
      "Status":"PNE",
      "Errors":null,
      "EndTimestamp":"2011-09-09T23:31:53.102Z",
      "Build":"9.1.6.10",
      "ChannelLineup":{
         "ServiceId":20494,
         "Name":"Los Angeles Area Channels - Los Angeles Area Broadcast",
         "City":"Los Angeles",
         "Type":"Broadcast",
         "MSO":"Data Services Product",
         "MSOID":"301530",
         "TimeZones":[
            {
               "StartDateTime":"2011-03-13T10:00:00Z",
               "EndDateTime":"2011-11-06T09:00:00Z",
               "Offset":-420
            }
         ],
         "Channels":[
            {
               "SourceId":11110,
               "Channel":"2.1",
               "CallLetters":"KCBSHD",
               "DisplayName":"KCBSHD",
               "SourceType":"Broadcast",
               "Type":"24-Hours",
               "Order":1,
               "TiVoSupported":true,
               "ParentNetworkId":2,
               "IconAvailable":true,
               "FullName":"KCBS HDTV",
               "VirtualChannelNumber":"2.1",
               "Affiliation":2165,
               "ServiceType":"Digital",
               "SourceAttributes":"1",
               "ChannelSchedules":null,
               "SourceAttributeTypes":[
                  "HD"
               ],
               "ChannelImages":[
                  {
                     "ImageUrl":"http:\/\/actual-url-concealed.jpg",
                     "ImageUseType":null,
                     "ImageId":28785,
                     "ImageTitle":"CBS",
                     "ImageCaption":"Source Logo",
                     "ObjectId":"11110",
                     "ObjectType":"Source",
                     "ObjectName":"CBS; CBS",
                     "Relevancy":true,
                     "ImageCredit":"CBS",
                     "ImageCreditDisplay":null,
                     "ImageCastWeight":null,
                     "ImageZoomLevel":"1",
                     "ImageHeadcount":null,
                     "ImageType":"Station Logo",
                     "ImageFormat":null,
                     "ImageHorizontalResolution":248,
                     "ImageVerticalResolution":251,
                     "ImageMaintainAspectFlag":null,
                     "ImageExpiryDateTime":null,
                     "LastUpdate":"2009-02-05T10:13:15.79Z",
                     "ImageFormatId":null,
                     "Orientation":"Portrait",
                     "AspectRatio":"1:1",
                     "ImageOwner":"CBS",
                     "ParentImageId":16786820,
                     "MaxImageScale":"100"
                  }
               ],
               "ChannelLocation":"",
               "DvbTriplets":null
            },
            {
               "SourceId":11287,
               "Channel":"4.1",
               "CallLetters":"KNBCHD",
               "DisplayName":"KNBCHD",
               "SourceType":"Broadcast",
               "Type":"24-Hours",
               "Order":2,
               "TiVoSupported":true,
               "ParentNetworkId":5,
               "IconAvailable":true,
               "FullName":"KNBC HDTV",
               "VirtualChannelNumber":"4.1",
               "Affiliation":1209,
               "ServiceType":"Digital",
               "SourceAttributes":"1",
               "ChannelSchedules":null,
               "SourceAttributeTypes":[
                  "HD"
               ],
               "ChannelImages":[
                  {
                     "ImageUrl":"http:\/\/actual-url-concealed.jpg",
                     "ImageUseType":null,
                     "ImageId":219,
                     "ImageTitle":"NBC",
                     "ImageCaption":"Source logo",
                     "ObjectId":"11287",
                     "ObjectType":"Source",
                     "ObjectName":"NBC; National Broadcast Company",
                     "Relevancy":true,
                     "ImageCredit":"NBC",
                     "ImageCreditDisplay":null,
                     "ImageCastWeight":null,
                     "ImageZoomLevel":"1",
                     "ImageHeadcount":null,
                     "ImageType":"Station Logo",
                     "ImageFormat":null,
                     "ImageHorizontalResolution":2000,
                     "ImageVerticalResolution":1907,
                     "ImageMaintainAspectFlag":null,
                     "ImageExpiryDateTime":null,
                     "LastUpdate":"2008-08-18T15:00:28.81Z",
                     "ImageFormatId":null,
                     "Orientation":"Landscape",
                     "AspectRatio":"1:1",
                     "ImageOwner":"NBC",
                     "ParentImageId":16777425,
                     "MaxImageScale":"100"
                  }
               ],
               "ChannelLocation":"",
               "DvbTriplets":null
            }
         ]
      }
   }
}

XML Response Example

Here's an XML response to Request Example 1, which asks for the channel lineup for Los Angeles Area broadcast channels. The response has been edited to reduce the length.

Requested with http://api.rovicorp.com/TVlistings/v9/listings/servicedetails/serviceid/20494/info?locale=en-US&
format=xml&apikey=apikey&sig=sig
.

<GetServiceDetailsResult xmlns="http://services.macrovision.com/v9/listings" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:default="http://services.macrovision.com/v9/common/types">
  <default:RequestId xmlns="http://services.macrovision.com/v9/common/types">dc9bfcbd-fd01-483b-b8f1-a68078ec102e</default:RequestId>
  <default:TimeStamp xmlns="http://services.macrovision.com/v9/common/types">2011-09-09T23:40:02.131Z</default:TimeStamp>
  <default:Status xmlns="http://services.macrovision.com/v9/common/types">PNE</default:Status>
  <default:Errors xmlns="http://services.macrovision.com/v9/common/types"/>
  <default:EndTimestamp xmlns="http://services.macrovision.com/v9/common/types">2011-09-09T23:40:02.147Z</default:EndTimestamp>
  <default:Build xmlns="http://services.macrovision.com/v9/common/types">9.1.6.10</default:Build>
  <ChannelLineup>
    <ServiceId>20494</ServiceId>
    <Name>Los Angeles Area Channels - Los Angeles Area Broadcast</Name>
    <City>Los Angeles</City>
    <Type>Broadcast</Type>
    <MSO>Data Services Product</MSO>
    <MSOID>301530</MSOID>
    <TimeZones>
      <TimeZoneInfo>
        <StartDateTime>2011-03-13T10:00:00Z</StartDateTime>
        <EndDateTime>2011-11-06T09:00:00Z</EndDateTime>
        <Offset>-420</Offset>
      </TimeZoneInfo>
    </TimeZones>
    <Channels>
      <ListingsChannel SourceId="11110" Channel="2.1" CallLetters="KCBSHD" DisplayName="KCBSHD" SourceType="Broadcast" Type="24-Hours" Order="1" TiVoSupported="true" ParentNetworkId="2" IconAvailable="true" FullName="KCBS HDTV" VirtualChannelNumber="2.1" Affiliation="2165" ServiceType="Digital" SourceAttributes="1">
        <ChannelSchedules/>
        <SourceAttributeTypes>
          <SourceAttributeType>HD</SourceAttributeType>
        </SourceAttributeTypes>
        <ChannelImages>
          <Image>
            <ImageUrl>http://actual-url-concealed.jpg</ImageUrl>
            <ImageUseType xsi:nil="true"/>
            <ImageId>28785</ImageId>
            <ImageTitle>CBS</ImageTitle>
            <ImageCaption>Source Logo</ImageCaption>
            <ObjectId>11110</ObjectId>
            <ObjectType>Source</ObjectType>
            <ObjectName>CBS; CBS</ObjectName>
            <Relevancy>true</Relevancy>
            <ImageCredit>CBS</ImageCredit>
            <ImageCreditDisplay xsi:nil="true"/>
            <ImageCastWeight xsi:nil="true"/>
            <ImageZoomLevel>1</ImageZoomLevel>
            <ImageHeadcount xsi:nil="true"/>
            <ImageType>Station Logo</ImageType>
            <ImageFormat xsi:nil="true"/>
            <ImageHorizontalResolution>248</ImageHorizontalResolution>
            <ImageVerticalResolution>251</ImageVerticalResolution>
            <ImageMaintainAspectFlag xsi:nil="true"/>
            <ImageExpiryDateTime xsi:nil="true"/>
            <LastUpdate>2009-02-05T10:13:15.79Z</LastUpdate>
            <ImageFormatId xsi:nil="true"/>
            <Orientation>Portrait</Orientation>
            <AspectRatio>1:1</AspectRatio>
            <ImageOwner>CBS</ImageOwner>
            <ParentImageId>16786820</ParentImageId>
            <MaxImageScale>100</MaxImageScale>
          </Image>
        </ChannelImages>
        <ChannelLocation/>
        <DvbTriplets/>
      </ListingsChannel>
      <ListingsChannel SourceId="11287" Channel="4.1" CallLetters="KNBCHD" DisplayName="KNBCHD" SourceType="Broadcast" Type="24-Hours" Order="2" TiVoSupported="true" ParentNetworkId="5" IconAvailable="true" FullName="KNBC HDTV" VirtualChannelNumber="4.1" Affiliation="1209" ServiceType="Digital" SourceAttributes="1">
        <ChannelSchedules/>
        <SourceAttributeTypes>
          <SourceAttributeType>HD</SourceAttributeType>
        </SourceAttributeTypes>
        <ChannelImages>
          <Image>
            <ImageUrl>http://actual-url-concealed.jpg</ImageUrl>
            <ImageUseType xsi:nil="true"/>
            <ImageId>219</ImageId>
            <ImageTitle>NBC</ImageTitle>
            <ImageCaption>Source logo</ImageCaption>
            <ObjectId>11287</ObjectId>
            <ObjectType>Source</ObjectType>
            <ObjectName>NBC; National Broadcast Company</ObjectName>
            <Relevancy>true</Relevancy>
            <ImageCredit>NBC</ImageCredit>
            <ImageCreditDisplay xsi:nil="true"/>
            <ImageCastWeight xsi:nil="true"/>
            <ImageZoomLevel>1</ImageZoomLevel>
            <ImageHeadcount xsi:nil="true"/>
            <ImageType>Station Logo</ImageType>
            <ImageFormat xsi:nil="true"/>
            <ImageHorizontalResolution>2000</ImageHorizontalResolution>
            <ImageVerticalResolution>1907</ImageVerticalResolution>
            <ImageMaintainAspectFlag xsi:nil="true"/>
            <ImageExpiryDateTime xsi:nil="true"/>
            <LastUpdate>2008-08-18T15:00:28.81Z</LastUpdate>
            <ImageFormatId xsi:nil="true"/>
            <Orientation>Landscape</Orientation>
            <AspectRatio>1:1</AspectRatio>
            <ImageOwner>NBC</ImageOwner>
            <ParentImageId>16777425</ParentImageId>
            <MaxImageScale>100</MaxImageScale>
          </Image>
        </ChannelImages>
        <ChannelLocation/>
        <DvbTriplets/>
      </ListingsChannel>
    </Channels>
  </ChannelLineup>
</GetServiceDetailsResult>

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

Personal tools