Build Status Dependency Status Code Climate Coverage Status Gem Version

ThetvdbApi

thetvdb_api is a simple ruby client for accessing TV shows information from the thetvdb.com API.

Getting started

You can add it to your Gemfile with:

gem 'thetvdb_api'

Run the bundle command to install it.

After you install ThetvdbApi and add it to your Gemfile, you need to run the generator (if you use Ruby on Rails application):

rails generate thetvdb_api:install

The generator will install an initializer where you must past your api_key, and can past: language (2 letters abbrevation).

How to use

There is one entry point, in initialize you can past hash with api_key and language values, or leave empty:

client = ThetvdbApi::Client.new(api_key: '...', language: 'en')

Search series by name

client = ThetvdbApi::Client.new
client.search.get_series('buffy')
client.search.get_series_by_imdb_id('...')
client.search.get_series_by_zap2it_id('...')
client.search.get_episode('123', air_date)

Search series by id

client = ThetvdbApi::Client.new
client.series.find('123')
client.series.find_full('123')

Return series actors

client = ThetvdbApi::Client.new
client.actor.all(series_id)

Return series banners

client = ThetvdbApi::Client.new
client.banner.all(series_id)

Return series episode

client = ThetvdbApi::Client.new
client.episode.find_by_default_order(series_id, season, episode)
client.episode.find_by_dvd_order(series_id, season, episode)
client.episode.find_by_absolute_order(series_id, absolute)
client.episode.find(episode_id)

Get updates

client = ThetvdbApi::Client.new
client.update.day
client.update.week
client.update.month
client.update.all

ThetvdbApi return response class with pure xml (in body method) string fetched by Faraday, but it can be automatically mapped to Object. I have prepared some class for it which using happymapper gem. You should pass mapper options at the end of method arguments.

require 'thetvdb_api/mappers/update'
client = ThetvdbApi::Client.new
client.update.day(mapper: ThetvdbApi::Mappers::Update)

Mappers for:

require 'thetvdb_api/mappers/search_series'
client = ThetvdbApi::Client.new
client.search.get_series('buffy', mapper: ThetvdbApi::Mappers::SearchSeries)
client.search.get_series_by_imdb_id('...', mapper: ThetvdbApi::Mappers::SearchSeries)
client.search.get_series_by_zap2it_id('...', mapper: ThetvdbApi::Mappers::SearchSeries)

require 'thetvdb_api/mappers/search_episode'
client = ThetvdbApi::Client.new
client.search.get_episode('123', air_date, mapper: ThetvdbApi::Mappers::SearchEpisode)

Series

require 'thetvdb_api/mappers/series'
client = ThetvdbApi::Client.new
client.series.find('123', mapper: ThetvdbApi::Mappers::Series)

require 'thetvdb_api/mappers/full_series'
client = ThetvdbApi::Client.new
client.series.find_full('123', mapper: ThetvdbApi::Mappers::FullSeries)

Actors

require 'thetvdb_api/mappers/actors'
client = ThetvdbApi::Client.new
client.actor.all(series_id, mapper: ThetvdbApi::Mappers::Actors)

Banners

require 'thetvdb_api/mappers/banners'
client = ThetvdbApi::Client.new
client.banner.all(series_id, mapper: ThetvdbApi::Mappers::Banners)

Episodes

require 'thetvdb_api/mappers/episode'
client = ThetvdbApi::Client.new
client.episode.find_by_default_order(series_id, season, episode, mapper: ThetvdbApi::Mappers::Episode)
client.episode.find_by_dvd_order(series_id, season, episode, mapper: ThetvdbApi::Mappers::Episode)
client.episode.find_by_absolute_order(series_id, absolute, mapper: ThetvdbApi::Mappers::Episode)
client.episode.find(episode_id, mapper: ThetvdbApi::Mappers::Episode)

Updates

require 'thetvdb_api/mappers/update'
client = ThetvdbApi::Client.new
client.update.day(mapper: ThetvdbApi::Mappers::Update)

You can write own mappers which parse xml and convert it to hash. Remember that your class must have "parse" class method.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request