FAQ

TiVo Metadata Cloud Services 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 includes TiVo’s entertainment metadata – Video, Sports, and Digital First APIs

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

Contact TiVo Sales to convert your trial keys into commercial keys

The Terms of Service for using are available here.

Log into your account and select My Account. Your usage limits are specified on the line “Access Expiration”

We host our documentation here.

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

For faster, easier application development, TiVo 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

The templates you are authorized to use are contained in your templates file. Your application must download your template file and use 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 TiVo template server returns a status code 304

The URL to your templates file is the only hard-coded URL in your TiVo Cloud application. All other requests to TiVo 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

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

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

To authenticate your requests, TiVo Cloud requires an HTTP 1.1 Authorization header that contains OAuth1.0a credentials. OAuth1.0a is an authentication protocol described by IETF RFC 5849

Here is an overview of TiVo Cloud authentication:

1. When you register with TiVo Cloud, we provide you with a Consumer Key (also called an API key) and a Consumer Secret Key
2. 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
3. The TiVo 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

One of the benefits of developing with URI templates is that the only TiVo 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 TiVo

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

Log into your account and Select My Account -> Templates. Click on the download templates link.

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

Click here or select “Report an Issue” from the main menu on this site. You can report a bug or submit enhancements request.