Online Video and Social APIs

Overview

Integrate online and over-the-top (OTT) video content and capabilities into your video product offerings. Online Video APIs offer curated links to thousands of online videos, thoroughly indexed and synced to TMS Unique IDs. 

Online Social APIs allow you to easily add relevant social media links to your interface, giving your users instant connection to broader content for thousands of movies and TV programs, all linked through TMS Unique IDs.

Audience

This document is intended for developers who want to integrate the Gracenote APIs into their websites and applications. It assumes you are familiar with the basic concepts of APIs, HTTP request methods and the REST style of software architecture.

Important Terminology

The followng definitions help you understand the structure of the Gracenote APIs:

• TMS rootId - The rootId is the universal ID for the program record of a TV show, TV episode, movie (theatrical or made-for-television) and sports event. It is universal for all program records with different title language/description and language work version. This ID domain is unique.
• TMS Id - The TMSId is specific to a program's title language/description and language/work version. For example, a movie record for the 3-D version with an English title and English description. This is the primary key of the program record and is used to relate to the schedule file in both TV and movie products. This Id domain is unique.
• Series - Series and episode records are related. Series records are the parent of episode records.
• Episode - An episode represents a separate installment of a serialized into which a television show is divided.
• Movies - A movie id represents a theatrical release or made-for-televison film.

Accessing the APIs

To use the APIs, structure the URLs as follows:

http://feeds.tmsapi.com/<version>/<resource>/<id>

• <version> is the API version number. In this example it will be v2.
• <resource> is one or more sub-elements.
• <id> is the unique identifier for a resource against a specific, known record.

At the moment, the Online Video Data API only supports XML responses. We plan to support JSON in the near future.

Accessing International Data

While the API will try to automatically detect the host region based on the description language of the provided TMS ID there is also an option to add a region parameter to any OVD OnConnect query.  Using this region parameter will ensure that an API request returns content matches for the desired region.

Using The Region Parameter

You can add the region parameter to any Online Video API request by adding &region=[region code] to the end of your existing query.

Example:

http://feeds.tmsapi.com/v2/movies/MV002964250000.xml?api_key={yourAPIkey}&region=au

In this example you will receive matches from hosts in the Australia region for the UK produced film Trainspotting.

Notice that a different response is generated when omitting the region parameter – since the TMS ID has a description language of EN-GB the API assumes you are looking for availability in the UK region.

http://feeds.tmsapi.com/v2/movies/MV002964250000.xml?api_key={yourAPIkey}

Available Region Codes

The following table lists the available regions and their associated code for accessing online video matches.

Entry Points

• /series - Retrieves series information
• /episodes - Rertrieve single or multiple episodes
• /movies - Retrieve single movie metadata
• /social - Retrieve social media links for single rootId

Error Handling

If an API call results in an error, we will return an HTTP status code in the header fields and in the message-body if applicable. A response code of 200 (OK) is returned for all requests that are successfully understood and processed. While using our APIs you may receive the following errors: