• Register

Quickstart Guide

Getting started with OnConnect APIs is easy. We offer a deep set of metadata that will enable you to build applications that entertainment fans will love.

The key to retrieving metadata is the tmsId. Many of our API methods require a tmsId as a parameter and we assign unique IDs to TV series, episodes, movies, celebrities, TV schedule lineups and sports teams and organizations.

Before we dive in here are some links that will provide you with more detailed documention of our APIs and a reference application that shows our APIs in action.

Get Started - Retrieving tmsIds

There are two basic ways you can retrieve tmsIds: via the Lineup methods and Program Search.

Lineups - What's On TV

Lineup methods enable you to develop a basic TV schedule grid to show which programs are on what channels and when.

  1. Find a lineup by entering a postal code such as 94103. This will return a list of channel lineups that are available in that postal code area.
    http://data.tmsapi.com/v1/lineups?postalCode=94103&api_key=your_api_key_here
  2. Once you have selected a lineup ID, you can enter it as a parameter in our Lineup Airings (TV Grid) call. In this case, I have selected the Comcast Digital lineup with a lineupId of USA-CA04487-X.
    http://data.tmsapi.com/v1/lineups/USA-CA04487-X/grid?startDateTime=2013-02-06T21%3A30Z&api_key=your_api_key_here. The response of this call will enable you to build out a grid-like display showing channel numbers and programs by time.
  3. If you want additional details about a particular show or movie you can retrieve the tmsId from the response and pass it to our Program Details method. It returns detailed metadata for any movie, show, eposide or sport record. In this example I have chosen an episode from 30 Rock with a tmsId of EP008483570125. I enter this tmsId as a parameter in the Program Details method to retrieve more detailed metadata about this episode such as a longDescription, listing of the cast, and more.
    http://data.tmsapi.com/v1/programs/EP008483570125?api_key=your_api_key_here
  4. You will also see a seriesId, which is the parent series or show for this episode. You can retrieve additional series level details by passing this id (185203 for 30 Rock) to the Series Details method.

Program Search

If you're not interested in building out a grid display, you can retrieve tmsIds using our Program Search method.

  1. The Program Search includes a number of parameters which allow you to craft a wide or granular search. For example, if I'm interested in finding all Movies with a keyword of "San Francisco", I enter San Francisco in the q parameter, add a queryFields type of "keywords", an entityType of "movie" and then I limit the search to movies with a title language of English. The query looks like this:
    http://data.tmsapi.com/v1/programs/search?q=San+Francisco&queryFields=keywords&entityType=movie&titleLang=en&api_key=your_api_key_here
    You can also control the number of results being returned and can offset the results to implement paging.
  2. The search results will return a limited amount of metadata and if you would like to retrieve more detailed information to build out a more detailed movie page, you can take the tmsId and pass it as a parameter to our Program Details method.
  3. From the search results above, I have chosen the movie "Sneakers" with a tmsId of MV000355930000. By passing that ID to the Program Details method, I can retrieve more detailed metadata for that movie including recommendations for movies that are like Sneakers, keywords, genres and a complete listing of cast and crew.
  4. Interested in getting more detailed information about one of the celebrities? Just retrieve the personId from the Program Details response and pass it to our Celebrity Details method. You get the idea...

Online Video and Social links

Once you have a tmsId, you can also find out where you can watch that show or movie online by using our Online Video Data API methods. 

  1. Let's use the 30 Rock episode ID we retrieved in the exercise above. You can pass that tmsId to the Single Episode Information method to retrieve all of the sources where you can watch that video online. The metadata returned includes a link to the asset, plus information on whether or not there is a fee to watch. Providers include Netflix, Hulu, Amazon, iTunes and more.
    http://feeds.tmsapi.com/v2/episodes/EP008483570125.xml?api_key=your_api_key_here
  2. Want to mashup with social media APIs such as Facebook and Twitter? We have mapped our tmsId to them as well as IMDB, Wikipedia and Rotten Tomatoes.
  3. We'll use the movie Sneakers as an example. Once you have retrieved the program details for this movie, you will pass the rootId of the movie to the Movies/Series method to retrieve social links for that movie.
    http://feeds.tmsapi.com/social/14216.xml?api_key=your_api_key_here