• Register

Online Video and Social APIs


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.


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:

  • <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.



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.


Available Region Codes

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

Region Code
Australia AU
Brazil BR
Canada CA
France FR
Germany DE
Italy IT
Mexico MX
Spain ES
Sweden SE
United Kingdom UK
United States US

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:

HTTP Response Code Description
200 - OK Request returned successfully
301 - Moved Permanently The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs.
304 - Not Modified If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code. The 304 response MUST NOT contain a message-body, and thus is always terminated by the first empty line after the header fields.
401 - Unauthorized The request requires user authentication.
403 - Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.
404 - Not Found The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.
500 - Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.
504 - Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.