Skip to main content

A clean, resource friendly and easy to use API for

Project description

pytvdbapi - A python API for
|statusimage| |coverageimage| |pypiimage|

**pytvdbapi** is a python API for thetvdb.com_ online database for tv-shows.
The API is designed to be as easy and intuitive as possible to use.

The API is designed to respect the functionality of thetvdb.com_ as far as

Key Features
* A clean and easy to use interface
* A well documented API
* Support for Python 2.6, 2.7, 3.3 and 3.4
* Thoroughly tested against all supported versions.

**pytvdbapi** depends on the following packages to function.

* `httplib2 <>`_

The easiest and recommended way to install **pytvdbapi** is to use pip_::

$pip install pytvdbapi

Depending on your platform, you may need root permission to execute the above

Tobias Röttger is kindly maintaining an ArchLinux package of **pytvdbapi** that
can be found `here <>`_.

To use the API you should apply for an API key for your particular application.
An API key can be obtained for free from thetvdb.com_. These are some of the things you
can do with **pytvdbapi**.

Create a db instance::

>>> from pytvdbapi import api
>>> db = api.TVDB('B43FF87DE395DF56')

Search for a show name::

>>> result ='Dexter', 'en')
>>> len(result)

Obtain a show instance and access the data::

>>> show = result[0]
>>> print(show.SeriesName)

>>> len(show) # List the number of seasons of the show, season 0 is the specials season

Access individual seasons::

>>> season = show[1]
>>> len(season) # List the number of episodes in the season, they start at index 1
>>> print(season.season_number)

Access an episode within the season::

>>> episode = season[2]
>>> print(episode.EpisodeNumber)
>>> print(episode.EpisodeName)

The documentation for **pytvdbapi** is hosted at and there is a
version over at `Readthedocs <>`__.

Known Issues
* **pytvdbapi** only works with Python 2.6, 2.7, 3.3 and 3.4
**NOT 3.0, 3.1 or 3.2**.
* **pytvdbapi** does currently **NOT** support the use of Proxy Servers.

If you find any bug or want to request a new feature to the API, please use
the `issue tracker <>`_
associated with the project.

Try to be as detailed as possible when filing a bug, preferably providing a
patch or a test case illustrating the issue.

To get in contact with me, you can send me an email at or you can follow me on twitter
`@fuzzycode <!/fuzzycode>`__

**pytvdbapi** is released under the `LGPL 3 <>`__ license. See the
LICENSE.txt file for more details.

.. |statusimage| image::
.. |coverageimage| image::
.. |pypiimage| image::

.. _PyPI:
.. _pip:


2014-10-28, 0.5.0
* Added find and filter functions to the Show and Season classes to allow searching for specific
* Added get_episode_by_air_date function to search for an episode by air date for a given series
* Update the get_episode function to allow downloading using *default*, *dvd* or *absolute* sort order.
* Update the get_series function to allow getting a series using imdb id and zap2it id.
* Speed up load times when downloading data
* Use zip format for retrieving series data.
* Bug fixes and code clean-up

2013-11-22, 0.4.0
* Removed support for Python 3.2
* Improved unicode support
* Improved compatibility with standard Python functions like *hasattr()* and *getattr()*
* Show, Season, Episode, Actor and Banner instances can now be pickled
* Added the get_episode() function to access an episode directly using the episode id.
* Added the option *ignore_case* to be able to access the attributes in a case insensitive manner.
* Added the *load_actors* and *load_banners* functions to load actors and banners on individual shows
* Fixed broken unit tests and improved test stability
* Bug fixes and code clean-up

2012-06-29, 0.3.0
* Added Actor objects to contain extended actor data
* Added Banner objects to contain extended banner data
* Added a get() function to access a show directly using the show id.
* Updated the status to Alpha

2012-04-16, 0.2.3
* Fixed an issue with missing data folder in package

2012-01-05, 0.2.2
* Updated author name to avoid unicode issues
* Improved the documentation

2011-12-17, 0.2.1
* Updated test coverage
* Made the source code PEP8 and Pylint compatible
* Updated documentation and prepared for PyPI release

2011-12-07, 0.2.0
* Updated to support Python 2.6, 2.7 and 3.2
* Made the interfaces cleaner by using collections.Mapping

2011-11-29, 0.1.1
* Renamed the package to pytvdbapi to avoid any confusion with the official service.
* Updated the to use setuptools if available

2011-11-28, 0.1.0
* Initial alpha release of the package.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytvdbapi-0.5.0.tar.gz (43.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page