Module: Tvdb2::API

Included in:
Client
Defined in:
lib/tvdb2/api.rb

Overview

TODO:

Missing endpoints are:

  • Series

    • filter: GET /series/{id}/filter

  • Updates

    • updadad: GET /updated/query

  • Users

    • user: GET /user

    • favorites: GET /user/favorites

    • delete favorites: DELETE /user/favorites/{id}

    • add favorites: PUT /user/favorites/{id}

    • ratings: GET /user/ratings

    • ratings with query: GET /user/ratings/query

    • delete rating: DELETE /user/ratings/{itemType}/{itemId}

    • add rating: PUT /user/ratings/{itemType}/{itemId}/{itemRating}

Methods in this module wrap the TVDB api endpoints.

Instance Method Summary collapse

Instance Method Details

#actors(id) ⇒ Array<TvdbStruct>

Perform a request to the endpoint GET /series/{id}/actors.

Parameters:

  • id (Integer) —

    the id of the series.

Returns:

  • (Array<TvdbStruct>) —

    actors for the given series id.

Raises:



114
115
116
 
# File 'lib/tvdb2/api.rb', line 114

def actors(id)
  build_array_result("/series/#{id}/actors")
end

#best_search(name) ⇒ Series

Returns the series that best match the name passed as parameter.

Parameters:

  • name (String) —

    name of the series to search for.

Returns:

  • (Series) —

    the series that best match the name passed as parameter.

Raises:



58
59
60
61
62
63
 
# File 'lib/tvdb2/api.rb', line 58

def best_search(name)
  results = search(name: name)
  chosen = results.select{|x| x.seriesName.downcase == name.downcase}.first
  chosen ||= results.select{|x| x.aliases.map(&:downcase).include?(name.downcase)}.first
  return chosen || results.first
end

#episode(id) ⇒ Episode

Perform a request to the endpoint GET /episodes/{id}.

Parameters:

  • id (Integer) —

    the id of the episode.

Returns:

  • (Episode) —

    the full information for a given episode id.

Raises:



123
124
125
 
# File 'lib/tvdb2/api.rb', line 123

def episode(id)
  build_object_result("/episodes/#{id}", {}, Episode)
end

#episodes(id, params = {}) ⇒ Array<Episode>

Perform a request to the endpoint GET /series/{id}/episodes.

Parameters:

  • id (Integer) —

    the id of the series.

  • params (Hash) (defaults to: {}) —

    the params of the request to retrieve the episodes of the series.

Options Hash (params):

  • :absoluteNumber (String, Integer) —

    absolute number of the episode;

  • :airedSeason (String, Integer) —

    aired season number;

  • :airedEpisode (String, Integer) —

    aired episode number;

  • :dvdSeason (String, Integer) —

    DVD season number;

  • :dvdEpisode (String, Integer) —

    DVD episode number;

  • :imdbId (String, Integer) —

    IMDB id of the series;

  • :page (Integer) —

    page of results to fetch (100 episodes per page).

Returns:

  • (Array<Episode>) —

    episodes found.

Raises:



101
102
103
104
105
106
107
 
# File 'lib/tvdb2/api.rb', line 101

def episodes(id, params = {})
  if params.nil? || params.empty?
    build_array_result("/series/#{id}/episodes", {}, Episode)
  else
    build_array_result("/series/#{id}/episodes/query", params, Episode)
  end
end

#images(id, params) ⇒ Array<TvdbStruct>

Perform a request to the endpoint GET /series/{id}/images/query.

Parameters:

  • id (Integer) —

    the id of the series.

  • params (Hash) —

    the params of the request to retrieve the images.

Options Hash (params):

  • :keyType (String) —

    type of image you're querying for (fanart, poster, season, seasonwide, series);

  • :resolution (String) —

    resolution to filter by (1280x1024 for example);

  • :subKey (String) —

    subkey for the above query keys.

Returns:

  • (Array<TvdbStruct>) —

    the images for a particular series.

Raises:



148
149
150
 
# File 'lib/tvdb2/api.rb', line 148

def images(id, params)
  build_array_result("/series/#{id}/images/query", params)
end

#images_summary(id) ⇒ Array<TvdbStruct>

Perform a request to the endpoint GET /series/{id}/images.

Parameters:

  • id (Integer) —

    the id of the series.

Returns:

  • (Array<TvdbStruct>) —

    a summary of the images for a particular series.

Raises:



133
134
135
 
# File 'lib/tvdb2/api.rb', line 133

def images_summary(id)
  build_object_result("/series/#{id}/images")
end

#language(id) ⇒ TvdbStruct

Perform a request to the endpoint GET /languages/{id}.

Parameters:

  • id (Integer) —

    language id.

Returns:

  • (TvdbStruct) —

    Information about a particular language.

Raises:



39
40
41
 
# File 'lib/tvdb2/api.rb', line 39

def language(id)
  build_object_result("/languages/#{id}")
end

#languages ⇒ Array<TvdbStruct>

Perform a request to the endpoint GET /languages.

Returns:

  • (Array<TvdbStruct>) —

    all available languages. These language abbreviations can be used in the Accept-Language header for routes that return translation records.

Raises:



30
31
32
 
# File 'lib/tvdb2/api.rb', line 30

def languages
  build_array_result('/languages')
end

#search(params) ⇒ Array<Series>

Perform a request to the endpoint GET /search/series.

Parameters:

  • params (Hash) —

    the params of the request.

Options Hash (params):

  • :name (String) —

    name of the series to search for;

  • :imdbId (String) —

    IMDB id of the series;

  • :zap2itId (String) —

    Zap2it id of the series to search for.

Returns:

  • (Array<Series>) —

    list of series found.

Raises:



51
52
53
 
# File 'lib/tvdb2/api.rb', line 51

def search(params)
  build_array_result('/search/series', params, Series)
end

#series(id) ⇒ Series

Perform a request to the endpoint GET /series/{id}.

Parameters:

  • id (Integer) —

    the id of the series.

Returns:

  • (Series) —

    a series record that contains all information known about a particular series id.

Raises:



71
72
73
 
# File 'lib/tvdb2/api.rb', line 71

def series(id)
  build_object_result("/series/#{id}", {}, Series)
end

#series_summary(id) ⇒ TvdbStruct

Perform a request to the endpoint GET /series/{id}/episodes/summary.

Parameters:

  • id (Integer) —

    the id of the series.

Returns:

  • (TvdbStruct) —

    a summary of the episodes and seasons available for the series.

Raises:



81
82
83
 
# File 'lib/tvdb2/api.rb', line 81

def series_summary(id)
  build_object_result("/series/#{id}/episodes/summary")
end