OnConnect Lookup APIs

Overview

Gracenote provides a wide range of entertainment information, including TV and movie schedules, comprehensive program information, and detailed celebrity details  The Data Delivery APIs now provide simple read-only access to this up-to-date entertainment information.  Additional services, such as Online Video and Social APIs and Media Cloud, can provide integration points for an even richer user entertainment experience.

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, JSON format, and the REST style of software architecture.  

Accessing the APIs

To use the Data Delivery APIs, use the following base URI for all API calls:

http://data.tmsapi.com/v1.1

Here is a sample call to get US lineups for zipcode 78701:

GET http://data.tmsapi.com/v1.1/lineups?country=USA&postalCode=78701&api_key=<your key>

Note that resource and parameter values which you pass to the APIs are case-sensitive.

Response format

Responses for Data Delivery APIs are currently delivered in JSON format only.

Responses for Online Video Data APIs are currently delivered in XML format only.

Please know that we are working on conversions for both APIs, so you won't have to remember the above, and can request either API response in JSON or XML. It will make us happier too!

JSONP Support

For client-side programming, responses can be delivered in JSONP format by appending parameter jsonp=<callback function name>.  You will need

to include dataType JSONP in the jquery get call. For example,  to wrap response in a callback function named  'handleLineups', the sample call would be:

http://data.tmsapi.com/v1.1/lineups?country=USA&postalCode=78701&jsonp=handleLineups&api_key=<your key>

GZip Support

To improve performance, we recommend requesting compressed responses using gzip. Add the following to the request header to enable gzip compression on responses:

Accept-encoding: gzip

Resources

Our APIs are organized around basic entertainment entities, such as lineups, programs, and, airings.  APIs can return single entities, called resources, or a list of entities, called collections.  All data is returned in JSON format.

The Data Delivery APIs provide read-only access to the following resources:

• Lineups: listing of available channel/stations, by geographic area and provider
• Stations: TV stations and related channels available in a lineup
• Programs: individual programs (TV shows, movies, sports events)
• Series: serialized programs (episodic TV shows, miniseries, talk shows)
• Movies: theatrical-release and made-for-TV movies
• Sports: program information specific to sports genre
• Celebrities: detailed personal information for celebrities

Important Gracenote Terms

The following definitions will help you understand the IDs and data structure of Gracenote's curated entertainment metadata.  All programs are assigned both a tmsId and a rootId.  TV series and episodes also have seriesId.

• tmsId – Unique ID for a program (show, movie, sports).  This ID is a 14-character alphanumeric field; it is the primary key of the program record, and is used to relate the program to TV schedules and Movie Showtimes. It is specific to a program’s title, description language, and version. The tmsId is the industry’s gold standard for recognizing and synchronizing entertainment assets.
  The first two letters of the tmsId indicate entity type:
  • SH = Show - includes TV specials, one-time shows, and series (non-episode-specific information)
  • EP = Episode - TV show episodes; metadata includes season number, episode number, and episode title; relates back to parent using a seriesId
  • MV = Movie - includes both theatrical releases and made-for-television films
• rootId – This numeric ID is used to identify all related program records with different title, description language, and version. 
• seriesId– This numeric ID is equivalent to the rootId of series' parent program record.  Only TV series programs (SH header record and EP episode records) will include seriesId.

Sample IDs for programs of each type:
(Note that this is a small sample of program type information.  For more detailed information, see Program Metadata.)