Ruby wrapper for TVDB API
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
examples [data_set] Add a bit more hash normalization for content Oct 14, 2012
lib Better implementation of the language setting. The client takes the o… Jul 2, 2013
spec Initial commit of gem Jan 18, 2011


The simple but complete ruby library for the TVDB apis. Created by Nathan Esquenazi for use at Miso.

Yes, there are a lot of libraries out there for this. I needed a few things that were different:

  • Easy way to 'verify' the correctness of a match beyond just title
  • An easy way to get all updates since a certain time, to keep our database synced
  • Easy helpers for accessing episodes from a series and the objects conceptually mapped to our existing schema.

Please reference the TVDB APIs to become familiar with the available actions and properties.


$ sudo gem install tvdbr


Create the tdvbr client:

tvdb ='API_KEY')

Get a series based on the id:

series = tvdb.find_series_by_id('1234')

Get a series based on a remote (IMDB) id:

series = tvdb.find_series_by_remote_id('tt0290978')

Get an episode based on the id:

episode = tvdb.find_episode_by_id('5678')

Get an episode based on the seriesid and airdate:

episode = tvdb.find_episode_by_airdate(80348, '2007-09-24')

Fetch a series based on the title:

dexter = tvdb.fetch_series_from_data(:title => "Dexter")
# => <#Tvbdr::Series>
dexter.title # => "Dexter"
dexter.actors # => ["Michael C. Hall", ...]
dexter.genres # => ["Drama", ...]
dexter.poster # => ""

Fetch a series based on the title and list of actors:

dexter = tvdb.fetch_series_from_data(:title => "Dexter", :starring => "Michael C. Hall, Jennifer Carpenter")

Get the episodes for a series:

series.episodes.each { |e| puts "#{} - S#{e.season_num}E#{e.episode_num}" }

Get the updated series since a given timestamp:

tvdb.each_updated_series(:since => do |series|
  puts "#{} - #{series.title}"

Get the updated episodes since a given timestamp:

tvdb.each_updated_episode(:since => do |episode|
  puts "#{} - #{} - #{episode.seriesid}"

You can also query using the newer static updates, by providing a 'period':

tvdb.each_updated_episode(:period => :day) do |episode|
  puts "#{} - #{} - #{episode.seriesid}"

You can provide day, week, or month to get complete data for that range of time.

Known Issues

  • None so far, but the gem is very young.
  • ...except I wrote this in a day or two and didn't write specs :(
  • ...but this will soon be corrected!