API Documentation

API Overview

TV Media provides comprehensive TV listing information to developers for use with their application. We offer access to our read-only, up-to-date data to power your apps.

Accessing APIs

To access TV Media's APIs, use the following base URL for all API calls:

GET http://api.tvmedia.ca/tv/v4

An example API call would be:

GET http://api.tvmedia.ca/tv/v4/lineups?postalCode=K4A0N9&api_key=YOUR API KEY

Check out more examples, or jump right into our Active Docs.

Licensing

TV Media provides a selection of commercial API subscription and pricing options. Send us a message with your application details and we'll get back to you with the more information and suggestions for the best plan for your needs.

Attribution

If your plan requires attribution, please use the below logo and hyperlink.

<a href="http://www.tvmedia.ca"><img src="https://developer.tvmedia.ca/images/TVMediaLogo.png"></a>

Download the logo here.

Response Formats

Responses for TV Media APIs are currently delivered in JSON format.

JSONP support is optional and can be delivered by adding the following parameter 'callback='

http://api.tvmedia.ca/tv/v4/lineups?postalCode=K4A0N9&callback=handleLineups&api_key=YOUR API KEY

Examples

Finding a lineup

A lineup is a collection of stations made available through a television provider. In order to access any tv listings a lineupID is required. So lets begin by selecting a lineup based on a ZIP/postal code. All we need are two parameters, api_key and postalCode:

request: http://api.tvmedia.ca/tv/v4/lineups?api_key={YOUR KEY}&postalCode=10001

response:

[
  {
    "lineupID":"6087",
    "lineupName":"RCN Cable-New York City, NY",
    "lineupType":"CAB",
    "providerID":"318",
    "providerName":"RCN Corporation",
    "serviceArea":"New York City, NY"
  },
  
  ...
  
  {
    "lineupID":"36211D",
    "lineupName":"Dish-New York, NY - Digital",
    "lineupType":"SAT",
    "providerID":"196",
    "providerName":"Dish Network",
    "serviceArea":"New York, NY "
  }
]

What we get back is a colection of lineup objects available for the given postal code. We can now choose one of the lineups and use its lineupID to start requesting TV listings.

TV Listings

Now that we found a lineup we can start requesting tv listings. There are many different tv listings endpoints available, we will start with the most general endpoint available from the lineups API. Lets say we wanted to watch movies or comedy shows, we can use the showtype parameter to filter everyting except movies and comedies (NOTE: not comedy movies, comedy shows AND movies) (See /genres/shows endpoint). We can also set the timezone for the listings to be displayed in, using the timezone parameter:

request: http://api.tvmedia.ca/tv/v4/lineups/6087/listings?api_key={YOUR KEY}&timezone=America/New_York&showtype[]=M&showtype[]=6&detail=brief

example response:

[
  {
    "number":"2",
    "channelNumber":2,
    "subChannelNumber":0,
    "stationID":1766,
    "callsign":"WCBS",
    "logoFilename":"cbs.png",
    "listDateTime":"2014-12-17 05:00:00",
    "duration":28,
    "showID":592267,
    "seriesID":61749,
    "showName":"Comics Unleashed",
    "episodeTitle":"",
    "repeat":false,
    "new":false,
    "live":false,
    "hd":false,
    "descriptiveVideo":false,
    "inProgress":false,
    "showTypeID":"6",
    "starRating":0,
    "description":"Young comedians discuss everything from pop culture to entertainment and more, bringing their best comedy to the stage.",
    "league":"",
    "team1":"",
    "team2":"",
    "showPicture":""
  },
  {
    "number":"15",
    "channelNumber":15,
    "subChannelNumber":0,
    "stationID":2574,
    "callsign":"WNJN",
    "logoFilename":"pbs.png",
    "listDateTime":"2014-12-17 07:00:00",
    "duration":60,
    "showID":1068825,
    "seriesID":119608,
    "showName":"Movie",
    "episodeTitle":"Curious George: A Very Monkey Christmas",
    "repeat":false,
    "new":false,
    "live":false,
    "hd":false,
    "descriptiveVideo":false,
    "inProgress":false,
    "showTypeID":"M",
    "starRating":2,
    "description":"George and the Man With the Yellow Hat are having a very merry time counting down the days until Christmas. There's only one puzzle, neither of them can figure out what to give the other for a present.",
    "league":"",
    "team1":"",
    "team2":"",
    "showPicture":"24088.jpg"
  }
]

Above is an example of two different listings we might get back. It's important to note that the showName for a movie listing becomes 'Movie' (or Cinéma for a french movie) and the actual movie title is in the episodeTitle field. To test for a movie listing check the showTypeID field for a value of 'M'

Date & Time parameters

If we want to find all airings of the movie 'Curious George: A Very Monkey Christmas' we can use the showID(1068825) returned from our last request and head over to the movies API (movieID's are displayed as showID's for tv listings).

Let's say we want to find all listings of the movie starting from December 17th 2014, 00:00 Eastern Time. The most important thing to note is that our start and end parameters must be in UTC time, and since Eastern Time during december is UTC-05:00, our start parameter would be the ISO 8601 equivalent of December 17th, 05:00 and our end parameter would be December 18th, 05:00. Again, it's important to note that the timezone parameter does NOT affect anything other than the listDateTime property returned in the response. All dates passed to the API must always be in UTC.

request: http://api.tvmedia.ca/tv/v4/movies/1068825/listings?api_key={YOUR KEY}&timezone=America/New_York&detail=brief&start=2014-12-17T05:00&end=2014-12-18T05:00&lineup=6087

example response:

[
  {
    "number":"15",
    "channelNumber":15,
    "subChannelNumber":0,
    "stationID":2574,
    "callsign":"WNJN",
    "logoFilename":"pbs.png",
    "listDateTime":"2014-12-17 12:00:00",
    "duration":60,
    "showID":1068825,
    "seriesID":119608,
    "showName":"Movie",
    "episodeTitle":"Curious George: A Very Monkey Christmas",
    "repeat":false,
    "new":false,
    "live":false,
    "hd":false,
    "descriptiveVideo":false,
    "inProgress":false,
    "showType":"Movies, Christmas, Children",
    "starRating":2,
    "description":"George and the Man With the Yellow Hat are having a very merry time counting down the days until Christmas. There's only one puzzle, neither of them can figure out what to give the other for a present.",
    "league":"",
    "team1":"",
    "team2":"",
    "showPicture":"24088.jpg"
  },
  {
    "number":"13",
    "channelNumber":13,
    "subChannelNumber":0,
    "stationID":1774,
    "callsign":"WNET",
    "logoFilename":"pbs.png",
    "listDateTime":"2014-12-17 13:00:00",
    "duration":60,
    "showID":1068825,
    "seriesID":119608,
    "showName":"Movie",
    "episodeTitle":"Curious George: A Very Monkey Christmas",
    "repeat":false,
    "new":false,
    "live":false,
    "hd":false,
    "descriptiveVideo":true,
    "inProgress":false,
    "showType":"Movies, Christmas, Children",
    "starRating":2,
    "description":"George and the Man With the Yellow Hat are having a very merry time counting down the days until Christmas. There's only one puzzle, neither of them can figure out what to give the other for a present.",
    "league":"",
    "team1":"",
    "team2":"",
    "showPicture":"24088.jpg"
  }
]

What we get back are two listings of the movie 'Curious George: A Very Monkey Christmas' that are airing on December 17th 2014, one at 12:00 and one at 13:00, Eastern Time (due to the timezone parameter we sent in the request).

Errors

All developer errors will result in an HTTP status code and json response containing the following properties:

Response Body

Property Type Description
httpCode integer HTTP status code
devMsg string Message containing information on why the request was not completed. This is not for end users, but for development and debugging purposes.
userMsg string End user message, tpyically empty or very general.

Status Codes

Below are a some status codes that you can expect to see returned:

  • 400 - Bad Request
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

Lineup Types

The following is a list of all the lineup types that correspond to the lineupType property of a lineup object.

Value Full Name
SAT Satellite
CAB Cable
OTA Over the Air
IPTV Internet Protocol Television

Generic Lineups

Applications on the sample plan are restricted to generic lineups that we have created. Developers on other plans also have access to these generic lineups. We created these lineups to include the most popular TV stations.

LineupID Name/Timezone
36617 US Generic - Eastern
41624 US Generic - Pacific
41625 US Generic - Mountain
41626 US Generic - Central
6340 Canada Generic - Eastern
6344 Canada Generic - Pacific
6345 Canada Generic - Mountain
6346 Canada Generic - Atlantic
6347 Canada Generic - Central

Leagues

The following is a list of all the leagues available to filter results.

Filter Show Type
3BA 3BA
RBS6 6 Nations Rugby
A11FL A-11 Football League
A-League A-League
ALS A-League Soccer
A1GP A1 Grand Prix
OAFL AFL Ontario
AL Airtricity League
JGTC All-Japan Grand Touring Car Championship
ACH Allan Cup Hockey
AAU Amateur Athletic Union
A.S.A. Amateur Softball Association
A.A. American Association
ABA American Basketball Association
ACHA American Collegiate Hockey Association
ACIS American Collegiate Intramural Sports
AFO American Fighting Organization
AHL American Hockey League
AIFA American Indoor Football Association
AMA American Motorcyclist Association
APBA American Power Boat Association
ASA American Speed Association
ATPA American Tractor Pullers Association
AYF American Youth Football
AF2 Arena Football 2
A.F.L. Arena Football League
ASL Argentine League
MLB-AFL Arizona Fall League
APGC Asia Pacific Golf 7Confederation
AFC Asian Football Confederation
AsianTour Asian Tour
AFA Asociación del Fútbol Argentino
ANFA Asociación Nacional de Fútbol Amateur
ANFP Asociación Nacional de Fútbol Profesional
AUF Asociación Uruguaya de Fútbol
AGP Association des golfeurs professionnels du Québec
ATP Association of Tennis Professionals
AVP Association of Volleyball Professionals
ALPB Atlantic League Professional Baseball
AU Atlantic University Sport
ABL Australian Baseball League
AFL Australian Football League
ARCA Automobile Racing Club of America
BWF Badminton World Federation
BALL Basketball Alumni League
BASS Bass Anglers Sportsman Society
BTUSA Beach Tennis USA
BNEFF Big North East Football Federation
BSL Brazilian Soccer League
BCJHL British Columbia Hockey League
BTCC British Touring Car Championship
BUY.com BUY.com Tour
CCL California Collegiate League
CBF Campeonato Brasileiro Série A
CBL Canadian Baseball League
CCAA Canadian Collegiate Athletic Association
CFL Canadian Football League
CHL Canadian Hockey League
CIS Canadian Interuniversity Sport
CJFL Canadian Junior Football League
CJHL Canadian Junior Hockey League
CLA Canadian Lacrosse Association
CLAX Canadian Lacrosse League
CPGT Canadian Professional Golf Tour
CSA Canadian Snowsports Association
CSL Canadian Soccer League
CWHL Canadian Women's Hockey League
CCBL Cape Cod Baseball League
CASCAR CASCAR
CPT Celebrity Players Tour
CEL Celtic League
CCHL Central Canadian Hockey League
CCHA Central Collegiate Hockey Association
CeHL Central Hockey League
CART Champ Car Series
Champ Champ Car World Series
CPIFL Champions Professional Indoor Football League
Champions Champions Series
CHAMPS Champions Tour
CORR Championship Off-Road Racing
CFA Chinese Football Association
C.S.L. Chinese Super League
FPC Colombian Professional Football
CSF Confederación Sudamericana de Fútbol
CONCACAF Confederation of North, Central American and Caribbean Association Football
CMLL Consejo Mundial de Lucha Libre
CBA Continental Basketball Association
CIFL Continental Indoor Football League
DSL Dutch Soccer League
ECHL East Coast Hockey League
ECAC Eastern College Athletic Conference
ELB Eastern League Baseball
FEF Ecuadorian Football League
EFL Empire Football League
ECB England and Wales Cricket Board
EPL English Premier League
EBSL Euro Beach Soccer League
ULEB EuroLeague Basketball
EPCR European Professional Club Rugby
ELET Evian Ladies European Tour
ECW Extreme Championship Wrestling
XFL Extreme Football League
EVP Extreme Volleyball Professionals
FFC Federación de Fútbol de Chile
FEI Fédération Equestre Internationale
FIA Fédération internationale de l'automobile
FIM Fédération internationale motocycliste
F.I.L. Federation of International Lacrosse
FRFU Florida Rugby Football Union
FC Football Conference
F1 Formula One
FFF French Football Federation
LNR French National Rugby League
FFR French Rugby Federation
FL Frontier League
GAA Gaelic Athletic Association
GFL Gateway Football League
GL German League
DTM German Touring Car Championship
Grand-Am Grand American Road Racing Association
GNCC Grand National Cross Country Off-Road Racing
GPAC Great Plains Athletic Conference
GNFA Greater Northwest Football Association
GOJHL Greater Ontario Junior Hockey League
GTHL Greater Toronto Hockey League
GUIN Guinness Premiership
HWB Hawaii Winter Baseball
HDRA High Desert Racing Association
H.S. High School
IWFL Independent Women's Football League
IPL Indian Premier League
I.F.L. Indoor Football League
IRL Indy Racing League
IndyCar IndyCar Series
IBL Intercounty Baseball League
IAAF International Association of Athletics Federations
IBAF International Baseball Federation
FIBA International Basketball Association
FIBT International Bobsleigh and Tobogganing Federation
ICC International Cricket Council
UCI International Cycling Union
IFAF International Federation of American Football
IFSA International Federation of Strength Athletes
FIVB International Federation of Volleyball
IFL International Fight League
FIFA International Football Association
IHL International Hockey League
IHBA International Hot Boat Association
IHRA International Hot Rod Association
IIHF International Ice Hockey Federation
IJSBA International Jet Sports Boating Association
FIL International Luge Federation
IMSA International Motor Sports Association
IRT International Racquetball Tour
IRB International Rugby Board
ISU International Skating Union
FIS International Ski Federation
ISF International Snowboard Federation
ISKA International Sport Karate Association
FINA International Swimming Federation
ITTF International Table Tennis Federation
ITF International Tennis Federation
ITU International Triathlon Union
FISU International University Sports Federation
IRFU Irish Rugby Football Union
ISL Island Soccer League
I.B.L. Israel Baseball League
FIGC Italian Football Federation
JSL Japan Soccer League
KHL Kontinental Hockey League
K-League Korean Professional Football League
La Liga La Liga
LET Ladies European Tour
LPGA Ladies Professional Golf Association
LNB League Nationale de Basketball
L1O League1 Ontario
Serie A Lega Serie A
L.F.P. Liga de Fútbol Profesional
LMB Liga Mexicana de Beisbol
LNBP Liga Nacional de Baloncesto Profesional
LPFP Liga Portuguesa de Futebol Profissional
LFP Ligue de Football Professionnel
LNAH Ligue nord-américaine de hockey
MISL Major Indoor Soccer League
MLB Major League Baseball
MLBPA Major League Baseball Players Association
MLL Major League Lacrosse
MLS Major League Soccer
MSL Major Series Lacrosse
MJAHL Maritime Junior A Hockey League
MRDA Men's Roller Derby Association
MFL Mexican Football League
MILB Minor League Baseball
MSA Motor Sports Association
NASCAR National Association for Stock Car Auto Racing
NAIA National Association of Intercollegiate Athletics
NBA National Basketball Association
NBDL National Basketball Development League
NBLC National Basketball League of Canada
NCTA National Capital Tennis Association
NCCAA National Christian College Athletic Association
NCAA National Collegiate Athletic Association
NCL National Cricket League
NFL National Football League
NFL Eu National Football League Eu rope
NHSRA National High School Rodeo Association
NHL National Hockey League
NHRA National Hot Rod Association
NJCAA National Junior College Athletic Association
NLL National Lacrosse League
NPL National Premier League
NPF National Pro Fastpitch
NPGL National Pro Grid League
NPSL National Professional Soccer League
NRL National Rugby League
NSCRA National Sport Compact Racing Association
NASTAR National Standard Race
NTRA National Thoroughbred Racing Association
NVL National Volleyball League
NWHL National Women's Hockey League
NWSL National Women's Soccer League
NWT Nationwide Tour
NECBL New England Collegiate Baseball League
NEFL New England Football League
NZRU New Zealand Rugby Union
NLSHL Newfoundland Senior Hockey League
NPB Nippon Professional Baseball
NAFL North American Football League
NAHL North American Hockey League
NALL North American Lacrosse League
NAPT North American Poker Tour
NASL North American Soccer League
NFC Northern Football Conference
NLB Northern League Baseball
NWAACC Northwest Athletic Association of Community Colleges
NWL Northwest League
NSSL Nova Scotia Soccer League
O.F.C. Oceania Football Confederation
OneAsia One Asia Tour
OBHA Ontario Ball Hockey Association
OCAA Ontario Colleges Atheltic Assocation
OFSAA Ontario Federation of School Athletic Associations
OFC Ontario Football Conference
OHL Ontario Hockey League
OJHL Ontario Junior Hockey League
OLA Ontario Lacrosse Association
ORU Ontario Rugby Union
OUA Ontario University Association
OVFL Ontario Varsity Football League
OWL Ontario Women's League
OYSL Ontario Youth Soccer League
OCSL Ottawa Carleton Soccer League
PCL Pacific Coast League
PJHL Pacific Junior Hockey League
EPGA PGA European Tour
P.B.A. Philippine Basketball Association
PCSL Portuguese Canadian Soccer League
PBL Premier Basketball League
PPL Pro Parkour League
PWS Pro Wrestling Superstars
PBA Professional Bowling Association
PBR Professional Bull Riding
PGA Professional Golf Association
APGA Professional Golf Association of Austalasia
PIFL Professional Indoor Football League
PRCA Professional Rodeo Cowboys Association
PSA Professional Squash Association
PWBA Professional Women's Bowling Association
QJAAAHL Quebec Junior AAA Hockey League
QMJHL Québec Major Junior Hockey League
RAFL Regional American Football League
RSEQ Réseau du sport étudiant du Québec
RCGA Royal Canadian Golf Association
RFL Rugby Football League
RFU Rugby Football Union
RLIF Rugby League International Federation
RSL Rugby Super League
RPL Russian Premier League
SCORE SCORE International
SFA Scottish Football Association
SFL Scottish Football League
SPL Scottish Premier League
SPFL Scottish Professional Football League
SPGA Senior Professional Golf Association
SkateCan Skate Canada
SDAHA South Dakota Amateur Hockey Association
SCTG Southern California Team Golf
SPHL Southern Professional Hockey League
SSL Spanish Soccer League
SCCA Sports Car Club of America
SLPL Sri Lanka Premier League
SCSA Stock Car Speed Association
ST Sunshine Tour
S.L. Super League
SR Super Rugby
SLG Superleague Greece
SEL Swedish Elite League
TXRD Texas Roller Derby
FA The Football Association
F.L. The Football League
LEGENDS The Legends Tour
TTR Ticket to Ride
Top 14 Top 14
TRW Top Ranked Wrestling
ToRD Toronto Roller Derby
TNA Total Nonstop Action
AAA Triple-A Baseball
TBL Türkiye Basketbol Federasyonu
UFC Ultimate Fighting Championship
UIM Union Internationale Motonotique
UDTRA United Dirt Track Racing Association
UEFA United European Football Association
UFL United Football League
UHL United Hockey League
UIF United Indoor Football
UIFL United Indoor Football League
USL United Soccer League
USL-2 United Soccer League Second Division
USAR United Speed Alliance Racing
USAS United States Aquatic Sports
USAC United States Auto Club
USBC United States Bowling Congress
USEF United States Equestrian Federation
USFSA United States Figure Skating Association
USFL United States Football League
USGA United States Golf Association
USHL United States Hockey League
USSA United States Ski Association
USSF United States Soccer Federation
USTA United States Tennis Association
UNL UNL
USATF USA Track and Field
USL-PDL USL Premier Development League
USL-P USL Professional Division
USSFD2 USSF Division 2 Profession League
WL W-League
Web.com Web.com Tour
WCL West Coast League
WCSHL West Coast Senior Hockey League
WICB West Indies Cricket Board
WHL Western Hockey League
WLA Western Lacrosse Association
WMBL Western Major Baseball League
WFTDA Women's Flat Track Derby Association
WFA Women's Football Alliance
WNBA Women's National Basketball Association
WPBA Women's Professional Billiards Association
W.P.B.A. Women's Professional Bowling Association
WPRO Women's Professional Racquetball Organization
WPS Women's Professional Soccer
W.S.A. Women's Squash Association
WTA Women's Tennis Association
WUSA Women's United Soccer Association
WBF World Baseball Federation
WBC World Boxing Counsel
WFL World Football League
WPT World Poker Tour
WSB World Series Boxing
WSL World Skating League
WSA World Snocross Association
WTP World Team Poker
WTT World Team Tennis
WTBA World Tenpin Bowling Association

Images


Pictures

Show pictures are available in two sizes following. These pictures are the filename returned in "picture". Note: Picture fields will soon be discontinued, please use artwork references.

200x200 Thumnbail
http://cdn.tvpassport.com/image/show/200x200/{provided filename}

Full image
http://cdn.tvpassport.com/image/show/lrg/{provided filename}


Artwork

Artwork is returned as an array that specifies the types of artwork that is available. Artwork can be accessed at various sizes. Note: Not all types of artwork are available for each series/episode.

Show Card
http://cdn.tvpassport.com/image/show/{size}/{provided filename}
A representation of a TV series the features the series cast or a setting familiar to the series.

Title Card
http://cdn.tvpassport.com/image/show/{size}/{provided filename}
A representation of a TV series the features the series’ logo. The image may or may not have cast members or a setting from the series.

Poster
http://cdn.tvpassport.com/image/show/{size}/{provided filename}
A representation of a TV series the features the series cast or a setting familiar to the series as well as the logo.

Episodic
http://cdn.tvpassport.com/image/show/{size}/{provided filename}
A photo from an TV series episode.

Movie Poster
http://cdn.tvpassport.com/image/show/{size}/{provided filename}
A poster representation from a movie.

Movie Still
http://cdn.tvpassport.com/image/show/{size}/{provided filename}
A photo from a movie.

              
Property Size Size Size Size Size Orientation/Ratio
showcard 1920x1080 1280x720 960x540 480x270 240x135 H 16:9
titlecard 1920x1080 1280x720 960x540 480x270 240x135 H 16:9
episodic 1920x1080 1280x720 960x540 480x270 240x135 H 16:9
poster 960x1440 480x720 240x360 120x180 60x90 V 2:3
moviePoster 960x1440 480x720 240x360 120x180 60x90 V 2:3
movieStill 1920x1080 1280x720 960x540 480x270 240x135 H 16:9
We strongly recommend you only use the image size closest to your requirements.

Station Logos

Station logos are available at: http://cdn.tvpassport.com/image/station/size/{provided filename}
Station logo sizes can be one of the following:

100x100
Square logos
76x28
Bounded by maximum constraints
75x16
Bounded by maximum constraint

Sports Logos

League logos are available at: http://cdn.tvpassport.com/image/league/{provided filename}

Team logos are available at: http://cdn.tvpassport.com/image/team/{provided filename}
Please note, we do not provide logos for college teams.

External IDs

The Series, Seasons, Episodes, Movies and People models all contain an array referencing ID's pointing to external services. These ID's allow you to map to third party data providers. The availability of ID's may be limited based on your licensing agreements with the third party provider.

Name Description
IVA Endpoint referencing Internet Video Archive's Entertainment Express API (https://developer.iva-api.com/ )

Interactive Docs

View our interactive docs here.

If you are looking for our V2 interactive docs, they can be found here, please note these operations have been deprecated.