TvRest/V1/Services

Jump to: navigation, search

Listings/Services

Returns a list of the television service offerings for an area. This request provides an optional argument to limit the response to just the services of a single cable or satellite operator.

Your application should start with this request to get the service ID of the television service you want.

Syntax

listings/services/postalcode/postalcode/info?apikey=apikey&sig=sig&locale=locale&countrycode=countrycode [&msoid=msoid] [&format=format]

Request Example 1

Request the television service offerings for Beverly Hills 90210.

Request Example 2

Make a second request with the MSO ID to see just the services offered by Dish Network for Beverly Hills 90210.

Request Example 3

Request the television services for Ontario, Canada K1N 6N5.

Request Example 4

Request the television services for Bonn, Germany, with an XML response.

Request Parameters

Sort none.gif  Click to re-sort

Parameter Required Description
apikeyYesAccess code that authorizes your request for data from Rovi.
countrycodeYesCountry served by the television service, stated as the case-sensitive, two-letter country code:
  • AR
Argentina
  • SV
El Salvador
  • NI
Nicaragua
  • AT
Austria
  • FI
Finland
  • NO
Norway
  • BE
Belgium
  • FR
France
  • PA
Panama
  • BM
Bermuda
  • DE
Germany
  • PE
Peru
  • BO
Bolivia
  • GT
Guatemala
  • PL
Poland
  • BR
Brazil
  • HN
Honduras
  • PT
Portugal
  • CA
Canada
  • IE
Ireland
  • ES
Spain
  • CL
Chile
  • IT
Italy
  • SE
Sweden
  • CO
Colombia
  • JM
Jamaica
  • CH
Switzerland
  • CR
Costa Rica
  • LU
Luxembourg 
  • GB
United Kingdom*
  • DK
Denmark
  • MX
Mexico
  • US
United States
  • DO
Dominican Republic 
  • NL
Netherlands
  • VE
Venezuela
  • EC
Ecuador

* Includes Wales, Scotland, and Northern Ireland.

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.

postalcodeYesFor the U.S. and Canada, the postal code of the coverage area. For other country codes, specify zero. Replace a space in a postal code with a plus (+) or percent20 (%20) symbol.
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.
msoidNoID of a cable or satellite operator. Specify an MSO ID to return just the services offered by that operator. Not useful for national or broadcast services.

If you don't know the MSO ID for an operator, first request the list of services in an area and then look through the response for that operator.

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
Services Service [ ] The list of television service offerings.

JSON Response Example

Here's the response to Request Example 1, which asks for the television service offerings for Beverly Hills 90210. 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/services/postalcode/90210/info?locale=en-US&
countrycode=US&apikey=apikey&sig=sig
.

{
   "ServicesResult":{
      "RequestId":"697e5040-b832-4264-8a90-60a323c5031b",
      "TimeStamp":"2011-11-15T23:32:29.144Z",
      "Status":"PNE",
      "Errors":[

      ],
      "EndTimestamp":"2011-11-15T23:32:29.144Z",
      "Build":"CPS Phase v9 Build 9.7.3.1",
      "Services":{
         "Service":[
            {
               "ServiceClass":"CATV ",
               "ServiceId":"360861",
               "Name":"Beverly Hills - Time Warner Cable- Walnut\/Diamond Bar",
               "City":"Beverly Hills",
               "Type":"Cable",
               "MSO":"Time Warner Cable",
               "MSOID":"25",
               "SystemName":"Time Warner Cable- Walnut\/Diamond Bar",
               "TimeZones":[
                  {
                     "StartDateTime":"2011-11-06T09:00:00Z",
                     "EndDateTime":"2012-03-11T10:00:00Z",
                     "Offset":"-480"
                  }
               ]
            },
            {
               "ServiceClass":"CATV ",
               "ServiceId":"70867",
               "Name":"Redondo\/Van Nuys - Time Warner Cable- Walnut\/Diamond Bar",
               "City":"Redondo\/Van Nuys",
               "Type":"Cable",
               "MSO":"Time Warner Cable",
               "MSOID":"25",
               "SystemName":"Time Warner Cable- Walnut\/Diamond Bar",
               "TimeZones":[
                  {
                     "StartDateTime":"2011-11-06T09:00:00Z",
                     "EndDateTime":"2012-03-11T10:00:00Z",
                     "Offset":"-480"
                  }
               ]
            },
            {
               "ServiceClass":"MATV ",
               "ServiceId":"200753",
               "Name":"Beverly Hills - WSNET - Mulholland Estates",
               "City":"Beverly Hills",
               "Type":"Cable",
               "MSO":"WSNET",
               "MSOID":"1004",
               "SystemName":"WSNET - Mulholland Estates",
               "TimeZones":[
                  {
                     "StartDateTime":"2011-11-06T09:00:00Z",
                     "EndDateTime":"2012-03-11T10:00:00Z",
                     "Offset":"-480"
                  }
               ]
            }
         ]
      }
   }
}

XML Response Example

Here's the response to Request Example 2, which adds the MSO ID parameter to see just the services offered by Dish Network.

Requested with http://api.rovicorp.com/TVlistings/v9/listings/services/postalcode/90210/info?locale=en-US&
countrycode=US&msoid=300264&apikey=apikey&sig=sig
.

<?xml version="1.0" encoding="UTF-8"?>
<GetServicesResult xmlns="http://api.rovicorp.com/v9/listings">
   <RequestId xmlns="http://api.rovicorp.com/v9/common/types">c990434f-57fc-4458-aa43-87c20ce2cc95</RequestId>
   <TimeStamp xmlns="http://api.rovicorp.com/v9/common/types">2013-07-11T22:40:36.49Z</TimeStamp>
   <Status xmlns="http://api.rovicorp.com/v9/common/types">PNE</Status>
   <Errors xmlns="http://api.rovicorp.com/v9/common/types" />
   <EndTimestamp xmlns="http://api.rovicorp.com/v9/common/types">2013-07-11T22:40:36.506Z</EndTimestamp>
   <Build xmlns="http://api.rovicorp.com/v9/common/types">9.13.6</Build>
   <Services>
      <Service ServiceClass="DBS">
         <ServiceId>76426</ServiceId>
         <Name>Dish Network with Los Angeles Area Channels (Pacific)</Name>
         <City>Los Angeles</City>
         <Type>Satellite</Type>
         <MSO>Echostar Communications Corp.</MSO>
         <MSOID>300264</MSOID>
         <SystemName>Dish Network</SystemName>
         <TimeZones>
            <TimeZoneInfo>
               <StartDateTime>2013-03-10T10:00:00Z</StartDateTime>
               <EndDateTime>2013-11-03T09:00:00Z</EndDateTime>
               <Offset>-420</Offset>
            </TimeZoneInfo>
         </TimeZones>
      </Service>
      <Service ServiceClass="DBS">
         <ServiceId>63882</ServiceId>
         <Name>Dish Network with Pacific Time Zone Area Channels (Pacific)</Name>
         <City>Pacific Time Zone</City>
         <Type>Satellite</Type>
         <MSO>Echostar Communications Corp.</MSO>
         <MSOID>300264</MSOID>
         <SystemName>Dish Network</SystemName>
         <TimeZones>
            <TimeZoneInfo>
               <StartDateTime>2013-03-10T10:00:00Z</StartDateTime>
               <EndDateTime>2013-11-03T09:00:00Z</EndDateTime>
               <Offset>-420</Offset>
            </TimeZoneInfo>
         </TimeZones>
      </Service>
   </Services>
</GetServicesResult>

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