Frequently Asked Questions

Getting Started

What are Rovi Cloud APIs?

Rovi Cloud is a media API platform that enables the rapid creation and deployment of next-generation, IP-based entertainment experiences. The platform comprises a range of services that enable you to create or enhance applications, websites and devices to drive content consumption and increase revenue opportunities. The platform offers includes metadata, recommendations, search and remote access APIs, with even more coming soon.

How much does it cost for developers to use Rovi Cloud APIs?

During the trial period of 30 days, developers can access Rovi Cloud APIs for free. After that, please contact Rovi Sales to extend your trial period or engage with us commercially.

Can I launch my application commercially with trial keys?

Contact Rovi Sales to convert your trial keys into commercial keys.

Understanding Rovi Terms of Service

What are the Terms of Service for the Rovi APIs?

The Terms of Service for using Rovi Cloud are available here.

Usage Limits

What are my usage limits?

Log into your account and select My Account -> Entitlements. Your usage limits are specified on the line "Daily limit of API calls."

Support

How do I report a bug?

On the Support menu select Report an issue. Provide the details in the form.

How do I request a new feature?

On the Support menu select Report an issue. Then, in the Category list on the form, select New Enhancement.

Does Rovi offer Developer Support?

Rovi offers Developer Support Services that are designed to supplement your team’s skills with deep subject-matter expertise to help you to quickly build and deliver a uniquely branded, customized entertainment application from our cloud APIs. Services include standard ticketing and phone support at every tier level. Access to Developer Support consultants complements in-house development. Our consultants address your unique requests and help you prepare for validation testing. Contact Rovi Sales for more information.

Using the Rovi APIs

Where can I access documentation to try out the APIs?

We host our generic documentation here. After you register and log in to your account, you can access an interactive API Console that is customized to the privileges of your API key. After converting your key to a commercial key and select the features you want, the API Console will provide documentation for those features.

Where can I find my API key?

Log into your account and select My Account -> Entitlements. Your Consumer Key (also known as an API key) and Consumer Secret Key are shown there.

How can I find out how many calls have been made by my application today?

Log into your account and select My Account -> Usage Reports. Usage report statistics are typically delayed by up to 60 minutes.

What are URI templates?

For faster, easier application development, Rovi Cloud offers URI templates to specify API calls. A URI template is a simple specification of an API call that identifies parameters to be substituted before executing the call. The specification adheres to Internet standard [RFC 6570 URI template Level 1](http://tools.ietf.org/html/rfc6570#section-1.2).

How do I use URI templates?

The templates you are authorized to use are contained in your templates file. Your application downloads your templates file and uses the URI templates there to render API requests.

You should hard code the URL to your templates file and download it at application start, or once a day, depending on your implementation. If the file hasn't changed, the template server returns a status code 304.

The URL to your templates file is the only hard-coded URL in your Rovi Cloud application. All other requests to Rovi Cloud are rendered from the URI templates in the templates file.

When you look at your templates file, you notice pairs and arrays of JSON name/value strings. For example, the following name/value pair shows the template name "data_movie_ratings" followed by the value, which is the URI template:

"data_movie_ratings": "http://cloud.rovicorp.com/data/2/2/lookup/movie/{id}/ratings;country={country}"

So, to get the data_movie_ratings URI template, your application searches the file for the name "data_movie_ratings" and then grabs and uses the value, which is the URI template.

And here is a sample array you might find in the file:

"media_image": {
    "master": "http://cloud.rovicorp.com/media/v1/source/{id}",
    "sized": "http://cloud.rovicorp.com/media/v1/image/{zoom}/{size}/{aspect}/{id}.jpg"
}
Here your application searches for "media_image", then searches for either "master" or "sized", and then grabs the associated string value and uses that to render the API request.

When you have the URI template for the API request you want, follow these steps:

1. Replace the parameters in the URI template with the values you want. In the data_movie_ratings template, for example, you replace {id} with a movie ID.
    • The URI has no brackets after substitution.
    • Substitution itself is just a simple match-and-replace operation.
    • You must URL-encode every parameter value before replacing the parameter.
    • You can safely recognize parameters by name in your code because we would only remove parameters in a version upgrade.

2. Look for any unused, optional parameters in a loop and replace them with empty values. We may add optional parameters to URI templates in the current version of your templates file. Note these as resources for further application development.

3. Do not modify any other characters or perform additional URL encoding on the template as any modification will result in a 401 Unauthorized error.

4. For PUT and POST operations, you also need to generate a body for the request, following the schema provided for the template. Body schemas are static and not defined by the template file and do not change.

5. The result is your rendered API request. You can now add an OAuth 1.0a Authorization header and execute it.

Why does Rovi use URI templates?

URI templates offer a wide range of benefits:
    • Generally reduce the length of URIs.
    • Provide an easier method of delivering custom APIs.
    • Reduce the amount of data that servers pass to clients.
    • Provide a simple, standards-based syntax for specifying templates.
    • Offer existing libraries that minimize complexity to application development.
    • Provide the flexibility to dynamically generate a different route path pattern to avoid problems, or to deliver a faster response.
    • Allow you to forget about the fine points of URI construction. You just copy templates from the templates file and replace the bracketed elements with values or empty values.

How can I download my templates?

You can manually download your templates file after you register and log in. Go to My Account -> Templates.

Your application should download your templates file at application start, or once a day, depending on your implementation. If the file hasn't changed, the template server returns a status code 304.

The URL to your templates file is constructed like this:

    http://cloud.rovicorp.com/template/v1/(YourConsumerKey)/(YourFileVersion)/templates.json

Copy your Consumer Key from My Account -> Entitlements.

Your templates file version is /1/ when you first sign up. When an API upgrade changes the templates you are using, you are invited to upgrade your applications to your version /2/ templates file.

How do I authenticate my API calls?

To authenticate your requests, Rovi Cloud requires an HTTP 1.1 Authorization header that contains OAuth 1.0a credentials. OAuth 1.0a is an authentication protocol described by [IETF RFC 5849](https://tools.ietf.org/html/rfc5849).

Here is an overview of Rovi Cloud authentication:
■ When you register with Rovi Cloud, we provide you with a Consumer Key (also called an API key) and a Consumer Secret Key.
■ To make an API call, your application locates the URI template in the templates file and renders the URI:
    • You must URL encode your parameter values before substitution.
    • You must replace all unused parameters with an empty string.
    • You must NOT URL encode the rendered URI.
    • You must NOT modify the template (other than the parameter values) in any way.
    • Generate an OAuth 1.0a signature using your Consumer Key and Secret. Do not specify a realm, oauth_token, or token shared-secret in the calculation. Verify that your timestamp is accurate.
    • Include the OAuth credentials in the Authorization header.
■ The Rovi server validates your API call and returns the requested resource (or an error code for an error).
■ Generate a new OAuth 1.0a signature for every API call you make, using a different, unique nonce.

For details, see [Authorizing Your Requests](http://docs.rovicloudapi.apiary.io/#introduction/getting-started/authorizing-your-requests) in the Rovi Cloud API Documentation.

What do I do when you release a new version of my templates file?

One of the benefits of developing with URI templates is that the only Rovi Cloud version number you are concerned with is the version number of your templates file. That number is the integer in the next-to-last path segment in the file link, which is the /1/ in the link to your first templates file, like this:

http://cloud.rovicorp.com/template/v1/(YourConsumerKey)/1/templates.json

Each upgrade to your templates file increases the version number by one, so the /1/ becomes /2/ and then /3/ and so on. A version upgrade just indicates a breaking change, not whether the improvement is small or large.

If an upgrade does not change features you are using, you may choose to wait until a later version to upgrade. We might, however, ask you to upgrade for a critical change, such as for a security issue. The length of time you have to upgrade in such circumstances is specified in your contract with Rovi.

Before you upgrade, you can check out the changes in the new version and test them in the API Console. Log into your account and download the new version of your template as follows:

1. Log into your account.
2. Select My Account -> Templates.
3. Select the version you want to download.
4. Click Download.

After you upgrade and when no applications are calling a previous version, we may choose to end support for that version.