Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Ruby wrapper for TVDB API
branch: master
Failed to load latest commit information.
examples [data_set] Add a bit more hash normalization for content
lib Better implementation of the language setting. The client takes the o…
spec Initial commit of gem
.gitignore Initial commit of gem
Gemfile.lock Updated tvdbr to 0.2.1
LICENSE Create License file
NOTES Rename old readme to NOTES Updates README with new features
Rakefile Initial commit of gem
tvdbr.gemspec Update gemspec with license


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!
Something went wrong with that request. Please try again.