James Smith


TheTVDB.com is user contributed TV show and episode database which is used by many popular home theatre applications, such as XBMC to look up details of TV shows.

I’ve written a simple Python interface to their Programmer’s API which makes it possible for developers to extract the TV data they need from TheTVDB with minimal effort.

Let me know if you find this useful, or you use it in any real projects!


This module uses cElementTree (available in Python 2.5+) to traverse XML, so you’ll need Python 2.5 available. Alternatively if you have an older version of Python you can install cElementTree or ElementTree yourself, and modify the import line at the top of the file.


I’m not going to go into great detail about the interface because the module is fairly self explanatory, but here are a few of the main functions:


There are 2 classes, the Show class and the Episode class. Most functions in this API return either a Show object, an Episode object, or a list of IDs. I’m not going to document all of the properties in each object as these are visible in the module itself, but you’d usually access the public variables directly, e.g. episode.overview.



I’m releasing this under the GPL2 license. If you reuse it or improve it, please let me know!



About the Author

James Smith, British entrepreneur and developer based in San Francisco.

I'm the co-founder of Bugsnag with Simon Maynard, and from 2009 to 2012 I led up the product team as CTO of Heyzap.