Class: TheTvDbParty::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/thetvdb_party/client.rb

Overview

The TheTvDb API client

Remarks

If nil is specified for #apikey, the client will not be able to access the API successfully for most functions

The #search method will always be available, even if you do not have a valid API key.

Example
How to use a client to search for a series, and how to get its Base Series Record

Creates a new client an searches for “The Mentalist”

client = TheTvDbParty::Client.new "<myTheTvDbApiKey>"
searchResults = client.search "The Mentalist"
searchResults.each do |search_result_record|
  base_series_record = search_result_record.get_base_series_record
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(apikey = nil) ⇒ Client

Creates a new TheTvDb client with the given API key

Parameters
apikey

Optional. The API key to use when accessing the ThTvDb programmers API

Remarks

if apikey is nil, only the #get_series and #search methods will work, as they do not require an API key.


28
29
30
# File 'lib/thetvdb_party/client.rb', line 28

def initialize(apikey = nil)
  @apikey = apikey
end

Instance Attribute Details

#apikeyObject

The API key that is currently in use


17
18
19
# File 'lib/thetvdb_party/client.rb', line 17

def apikey
  @apikey
end

#languageObject

Accesses the language currently used by the client when accessing the TheTvDb API.


20
21
22
# File 'lib/thetvdb_party/client.rb', line 20

def language
  @language
end

Instance Method Details

#get_base_episode_record(episodeid) ⇒ Object

Retrieves the base episode record for an episode by its TheTvDb unique identifier

Parameters
episodeid

The unique episode identifier of the episode to access

Returns

A TheTvDbParty::BaseEpisodeRecord instance representing the episode, or nil if the record was not found.


77
78
79
80
81
82
83
84
85
# File 'lib/thetvdb_party/client.rb', line 77

def get_base_episode_record(episodeid)
  unless @language
    request_url = "#{@apikey}/episodes/#{episodeid}"
  else
    request_url = "#{@apikey}/episodes/#{episodeid}/#{@language}.xml"
  end
  request_url = URI::join(BASE_URL, 'api/', request_url)
  get_base_episode_record_from_url request_url
end

#get_base_series_record(seriesid) ⇒ Object

Retrieves the Base Series Record for a given series by its series id.

Parameters
seriesid

The TheTvDb assigned unique identifier for the series to access.

Returns

A TheTvDbParty::BaseSeriesRecord instance or nil if the series could not be found.


60
61
62
63
64
65
66
67
68
69
70
71
# File 'lib/thetvdb_party/client.rb', line 60

def get_base_series_record(seriesid)
  unless @language
    request_url = "#{@apikey}/series/#{seriesid}"
  else
    request_url = "#{@apikey}/series/#{seriesid}/#{@language}.xml"
  end
  request_url = URI.join(BASE_URL, 'api/', request_url)
  resp = self.class.get(request_url).parsed_response
  return nil unless resp["Data"]
  return nil unless resp["Data"]["Series"]
  BaseSeriesRecord.new(self, resp["Data"]["Series"])
end

#get_full_series_record(seriesid) ⇒ Object


196
197
198
199
200
201
202
203
204
205
206
207
208
209
# File 'lib/thetvdb_party/client.rb', line 196

def get_full_series_record(seriesid)
  unless @language
    request_url = "#{@apikey}/series/#{seriesid}/all"
  else
    request_url = "#{@apikey}/series/#{seriesid}/all/#{@language}.xml"
  end
  request_url = URI.join(BASE_URL, 'api/', request_url)

  resp = self.class.get(request_url).parsed_response

  return nil unless resp["Data"]

  FullSeriesRecord.new self, resp["Data"]
end

#get_series(seriesname) ⇒ Object

Alias for #search


33
# File 'lib/thetvdb_party/client.rb', line 33

def get_series(seriesname) search seriesname end

#get_series_absolute_episode(seriesid, episode_number) ⇒ Object

Retrieves the base episode record for an episode by its absolute ordering in a series.

Parameters
seriesid

The TheTvDb unique identifier for the series to which the episode belongs.

episode_number

The absolute episode number within the series

Returns

A TheTvDbParty::BaseEpisodeRecord instance representing the episode or nil if the record was not found.

Remarks

Specials episodes are ordered within season 0. Attributes within the returned record indicate at which time (i.e. between which episode the episode should be ordered)

See Also

#get_series_season_episode, #get_series_dvd_season_episode, #get_base_episode_record


130
131
132
133
134
135
136
137
138
# File 'lib/thetvdb_party/client.rb', line 130

def get_series_absolute_episode(seriesid, episode_number)
  unless @language
    request_url = "#{@apikey}/series/#{seriesid}/absolute/#{episode_number}"
  else
    request_url = "#{@apikey}/series/#{seriesid}/absolute/#{episode_number}/#{@language}.xml"
  end
  request_url = URI.join(BASE_URL, 'api/', request_url)
  get_base_episode_record_from_url request_url
end

#get_series_actors(seriesid) ⇒ Object

Retrieves the actors for a given series by its series id.

Parameters
seriesid

The TheTvDb assigned unique identifier for the series to access.

Returns

An array of TheTvDbParty::Actor instances or nil if the actors could not be retrieved. Note: may return [] if actors are retrieved but there are none.


164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
# File 'lib/thetvdb_party/client.rb', line 164

def get_series_actors(seriesid)
  request_url = "#{@apikey}/series/#{seriesid}/actors.xml"
  request_url = URI.join(BASE_URL, 'api/', request_url)
  response = self.class.get(request_url).parsed_response
  return nil unless response["Actors"]
  return nil unless response["Actors"]["Actor"]
  case response["Actors"]["Actor"]
    when Array
      response["Actors"]["Actor"].map {|s|Actor.new(self, s)}
    when Hash
      [Actor.new(self, response["Actors"]["Actor"])]
    else
      []
  end
end

#get_series_all(seriesid) ⇒ Object


180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# File 'lib/thetvdb_party/client.rb', line 180

def get_series_all(seriesid)
  unless @language
    request_url = "#{@apikey}/series/#{seriesid}/all/en.zip"
  else
    request_url = "#{@apikey}/series/#{seriesid}/all/#{@language}.zip"
  end

  request_url = URI.join(BASE_URL, 'api/', request_url)
  resp = self.class.get(request_url)

  return nil unless resp.body

  AllSeriesInformation.new(self, resp.body)

end

#get_series_banners(seriesid) ⇒ Object

Retrieves the banners for a given series by its series id.

Parameters
seriesid

The TheTvDb assigned unique identifier for the series to access.

Returns

An array of TheTvDbParty::Banner instances or nil if the banners could not be retrieved. Note: may return [] if banners are retrieved but there are none.


144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
# File 'lib/thetvdb_party/client.rb', line 144

def get_series_banners(seriesid)
  request_url = "#{@apikey}/series/#{seriesid}/banners.xml"
  request_url = URI.join(BASE_URL, 'api/', request_url)
  response = self.class.get(request_url).parsed_response
  return nil unless response["Banners"]
  return nil unless response["Banners"]["Banner"]
  case response["Banners"]["Banner"]
    when Array
      response["Banners"]["Banner"].map {|s|Banner.new(self, s)}
    when Hash
      [Banner.new(self, response["Banners"]["Banner"])]
    else
      []
  end
end

#get_series_dvd_season_episode(seriesid, season_number, episode_number) ⇒ Object

Retrieves the base episode record for an episode by its DVD ordering in a series.

Parameters
seriesid

The TheTvDb unique identifier for the series to which the episode belongs.

season_number

The number of the season in which the episode appeared.

episode_number

The episode number within the season

Returns

A TheTvDbParty::BaseEpisodeRecord instance representing the episode or nil if the record was not found.

Remarks

Specials episodes are ordered within season 0. Attributes within the returned record indicate at which time (i.e. between which episode the episode should be ordered)

See Also

#get_series_season_episode, #get_series_absolute_episode, #get_base_episode_record


113
114
115
116
117
118
119
120
121
# File 'lib/thetvdb_party/client.rb', line 113

def get_series_dvd_season_episode(seriesid, season_number, episode_number)
  unless @language
    request_url = "#{@apikey}/series/#{seriesid}/dvd/#{season_number}/#{episode_number}"
  else
    request_url = "#{@apikey}/series/#{seriesid}/dvd/#{season_number}/#{episode_number}/#{@language}.xml"
  end
  request_url = URI.join(BASE_URL, 'api/', request_url)
  get_base_episode_record_from_url request_url
end

#get_series_season_episode(seriesid, season_number, episode_number) ⇒ Object

Retrieves the base episode record for an episode by its default ordering in a series.

Parameters
seriesid

The TheTvDb unique identifier for the series to which the episode belongs.

season_number

The number of the season in which the episode appeared.

episode_number

The episode number within the season

Returns

A TheTvDbParty::BaseEpisodeRecord instance representing the episode or nil if the record was not found.

Remarks

Specials episodes are ordered within season 0. Attributes within the returned record indicate at which time (i.e. between which episode the episode should be ordered)

See Also

#get_series_dvd_season_episode, #get_series_absolute_episode, #get_base_episode_record


95
96
97
98
99
100
101
102
103
# File 'lib/thetvdb_party/client.rb', line 95

def get_series_season_episode(seriesid, season_number, episode_number)
  unless @language
    request_url = "#{@apikey}/series/#{seriesid}/default/#{season_number}/#{episode_number}"
  else
    request_url = "#{@apikey}/series/#{seriesid}/default/#{season_number}/#{episode_number}/#{@language}.xml"
  end
  request_url = URI.join(BASE_URL, 'api/', request_url)
  get_base_episode_record_from_url request_url
end

#get_updates_by_lastupdate(timestamp, type = "series") ⇒ Object


225
226
227
228
229
230
231
232
233
234
# File 'lib/thetvdb_party/client.rb', line 225

def get_updates_by_lastupdate(timestamp, type = "series")
  if(["series","episode","all","none"].index(type).nil? == false)
    request_url = "Updates.php?time=#{timestamp}&type=#{type}"
    request_url = URI.join(BASE_URL,'api/',request_url)
    
    resp = self.class.get(request_url)
    return nil unless resp.nil? == false
    return Update.new(self,resp,false)
  end
end

#get_updates_by_timeframe(timeframe) ⇒ Object


211
212
213
214
215
216
217
218
219
220
221
222
223
# File 'lib/thetvdb_party/client.rb', line 211

def get_updates_by_timeframe(timeframe)
  if(["day","week","month","all"].index(timeframe).nil? == false)
    request_url = "#{@apikey}/updates/updates_#{timeframe}.zip"
    request_url = URI.join(BASE_URL,'api/', request_url)
    
    resp = self.class.get(request_url)
    return nil unless resp.nil? == false
    return nil unless resp.body.nil? == false
    return Update.new(self,resp.body,true)
  else
    return nil
  end
end

#search(seriesname) ⇒ Object

This interface allows you to find the id of a series based on its name.

Parameters
seriesname

This is the string you want to search for. If there is an exact match for the parameter, it will be the first result returned.

Returns

An array of TheTvDbParty::SearchSeriesRecord instances that represent the search results. Empty if the search does not return any matches.

Remarks

The method call with the account identifier is currently not supported.

See Also

thetvdb.com/wiki/index.php?title=API:GetSeries


41
42
43
44
45
46
47
48
49
50
51
52
53
54
# File 'lib/thetvdb_party/client.rb', line 41

def search(seriesname)
  http_query = { :seriesname => seriesname }
  http_query[:language] = @language if @language
  response = self.class.get(URI::join(BASE_URL, 'api/', 'GetSeries.php'), { :query => http_query }).parsed_response
  return [] unless response["Data"]
  case response["Data"]["Series"]
    when Array
      response["Data"]["Series"].map {|s|SearchSeriesRecord.new(self, s)}
    when Hash
      [SearchSeriesRecord.new(self, response["Data"]["Series"])]
    else
      []
  end
end