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!