tv-listings

TV Listings API client for node.js

tv-listings is a node.js TV Media api wrapper. It provides access to TV listings for various cable and broadcast networks across the United States and Canada.

Requirements

• API Key from TV Media (free)

NOTE: The TV Media API limits usage to 500 queries per key per month. You can retrieve complete TV listings for multiple days in a single query, so this is not necessarily an issue. You'll just want to build your app with the mindset of retrieving a large dataset once and running sub-queries without going back to the API.

Installation

npm install tv-listings

Methods

• getLineups: Available lineups (providers) for a specific postal/zip code.
• getLineup: Channel information for a specific lineup.
• getListings: TV listings for a particular lineup grouped by channel.
• getListingsChrono: TV listings for a particular lineup in chronological order.
• getStation: Information on a specific station (channel) including logo.
• getStationListings: TV listings for a particular station (channel).

NOTE: The methods that retrieve TV listings can take some time to respond, depending on how large the result set is. I've noticed some issues requesting 3 or more days of listings across all channels in one query, but up to 2 days seems reliable.

NOTE: Every cable provider is not included, for example I've noticed Comcast and Fios are not listed while DirecTV and Dish are. I have Fios and use the Dish results. I'm sure there could be a few minor channel differences, but for widely broadcasted channels/shows it works fine.

Usage

Tutorial available here.

 
var tvAPI = require('tv-listings');
var tv = new tvAPI({
    apiKey: YOUR_TVMEDIA_KEY
});
 
tv.getLineups({ postalCode: "20001"}, function(err, results) {
    console.log(results);
});
 
tv.getLineup({ lineupID: "6076D" }, function(err, results) {
    console.log(results);
});
 
tv.getListings({ lineupID: "6076D", start: moment().format(), end: moment().add(1, 'days').format() }, function(err, results) {
    console.log(results);
});
 
tv.getListingsChrono({ lineupID: "6076D", sportEventsOnly: "true" }, function(err, results) {
    console.log(results);
});
 
tv.getStation({ stationID: "668" }, function(err, results) {
    console.log(results);    
});
 
tv.getStationListings({ stationID: "668" }, function(err, results) {
    console.log(results);
});
 

Sample Show Listing

{ 
    listDateTime: '2014-08-17 23:20:00',
    duration: '65',
    showID: '836963',
    seriesID: '136977',
    showName: 'Breaking Bad',
    episodeTitle: 'Bit by a Dead Bee',
    episodeNumber: '203',
    repeat: '0',
    new: '0',
    rating: 'TV14',
    captioned: '0',
    educational: '0',
    blackWhite: '0',
    subtitled: '0',
    live: '0',
    hd: '1',
    descriptiveVideo: '0',
    inProgress: '0',
    showType: 'Drama',
    year: '',
    guest: '',
    cast: 'Bryan Cranston, Anna Gunn, Aaron Paul',
    director: '',
    starRating: '0',
    description: 'Covering tracks means a less secure financial situation; the DEA have a break in the case.',
    league: '',
    team1: '',
    team2: '',
    event: null,
    location: '',
    showPicture: '21537.jpg',
    picture: 'http://api.tvmedia.ca/images/shows/21537.jpg' 
}

Sample Sports Listing

{ 
    listDateTime: '2014-08-17 20:00:00',
    duration: '180',
    showID: '101486',
    seriesID: '33461',
    showName: 'Football',
    episodeTitle: '',
    episodeNumber: '',
    repeat: '0',
    new: '0',
    rating: 'TVPG',
    captioned: '0',
    educational: '0',
    blackWhite: '0',
    subtitled: '0',
    live: '1',
    hd: '1',
    descriptiveVideo: '0',
    inProgress: '0',
    showType: 'Sports, Football',
    year: '',
    guest: '',
    cast: '',
    director: '',
    starRating: '0',
    description: 'Football.',
    league: 'NFL',
    team1: 'Denver Broncos',
    team2: 'San Francisco 49ers',
    event: 'Pre-season',
    location: 'Levi\'s Stadium, Santa Clara, Calif.',
    showPicture: '2580.jpg',
    picture: 'http://api.tvmedia.ca/images/shows/2580.jpg' 
}