ruby-tmdb3¶ ↑

ruby-tmdb3 is an ActiveRecord-style API wrapper for TheMovieDB.org (TMDb). ruby-tmdb3 uses tmdb’s API v3 and is designed to streamline common tasks associated with finding information about movies and cast members.

Installation¶ ↑

For ease of use ruby-tmdb3 is packaged as a Rubygem. Installing it is as simple as:

gem install ruby-tmdb3

Compatibility¶ ↑

Ruby 1.8.x & 1.9.x (2.0.x experimental)

Examples¶ ↑

require 'rubygems'
require 'ruby-tmdb3'

# setup your API key
Tmdb.api_key = "t478f8de5776c799de5a"

# (optional) setup your base url. This is provided for testing purposes by apiary.io when logged in.
# They provide a request and response log you can view from the web.
Tmdb.base_api_url = "http://private-xxxxx-themoviedb.apiary.io/3"

# setup your default language
Tmdb.default_language = "en"

# change your rate limit. Default is 0.34
Tmdb.rate_limit_time = 0.34

@movie = TmdbMovie.find(:title => "Iron Man", :limit => 1)
# => <OpenStruct>

@movie.title
# => "Iron Man"

Usage¶ ↑

There are 3 main methods you can use to get information about movies and cast members:

TmdbMovie.find([:id, :imdb, :title, :limit, :expand_results, :language])¶ ↑

Find information about an individual movie, or a set of movies that share a similar title, eg:

TmdbMovie.find(:title => "fight club", :limit => 10, :expand_results => true, :language => "en")

Parameters:

:id: Specifies an individual movie via it’s TMDb id
:title: Specifies a query string to look for in the movie titles
:imdb: Specifies an individual movie via it’s IMDB id
:limit: Specifies the maximum number of results to be returned
:expand_results: The TMDb API by default returns only partial info for any API method that can return multiple results. When :expand_results is set to true ruby-tmdb3 automatically makes extra API calls to fetch the full information for each item. This can result in very slow requests though. If you only need basic information for a search listing then set this to false. Defaults to ‘true’.
:language: Allows you to override the default API language on a per-query basis.

You must supply at least one of :id, :title, or :imdb. All other parameters are optional.

TmdbMovie.set_rating(id, rating, [:session_id])¶ ↑

:id: Specifies an individual movie via it’s TMDb id
:rating: What you want to set the rating to.
:session_id: (optional) If you don’t have a session id it will be provided after the first requet. One session_id should be used per user.

status_code, session_id, message = TmdbMovie.set_rating(1, 7.9)
> status_code
=> 1
> session_id
=> "1234"
> message
=> "success"

status_code, session_id, message = TmdbMovie.set_rating(2, 7.9, session_id: "1234")
> status_code
=> 1
> session_id
=> "1234"
> message
=> "success"

TmdbCast.find([:id, :name, :limit, :expand_results, :language])¶ ↑

Find information about an individual cast member, or a set of cast members sharing similar names, eg:

TmdbCast.find( :id => 123, :name => "Brad", :limit => 1, :expand_results => true)

:id: Specifies an individual cast member via their TMDb id
:name: Specifies a query string to look for in the cast names
:limit: See TmdbMovie
:expand_results: See TmdbMovie
:language: See TmdbMovie

You must supply at least one of :id or :name. All other parameters are optional.

TmdbList¶ ↑

TmdbList is a class with 5 main methods

list = TmdbList.upcoming
list = TmdbList.now_playing
list = TmdbList.top_rated
list = TmdbList.popular
list = TmdbList.changes

Each method except changes has an optional page and language arguments.

list = TmdbList.popular(2,"EN")

TmdbList.changes only has an options hash and the TmdbList:Movie objects are only populated with an id.

list = TmdbList.changes({page: 1, start_date: '2012-03-25', end_date: '2012-03-25', language: 'EN'})

:page: Each page returns 100 results
:start_date: Sets the start date for when a change occured
:end_date: Sets the end date for when a change occured
:language: See TmdbMovie

All parameters are optional. The defaults are {page: 1, start_date: Time.now.strftime(“%Y-%m-%d”), end_date: (Time.now+60*60*24).strftime(“%Y-%m-%d”), language: “EN” }

A TmdbList instance has theses accessors

attr_accessor :page, :total_pages, :total_results, :movies_data, :movies

And these methods

list.movie_ids #mapped array of movie id's

an array of tmdb movie ids.

list.movie_ids

the original json data returned from tmdb.

list.movies_data

an array of TmdbList::Movie objects.

list.movies

A TmdbList::Movie object has these accessors.

attr_accessor :backdrop_path, :id, :original_title, :release_date, :poster_path, :title, :vote_average, :vote_count

Usage Examples¶ ↑

Find all movies whose titles match a given string:

@movies = TmdbMovie.find(:title => 'Iron Man')

Find the movie most likely to be associated with a given title:

@movie = TmdbMovie.find(:title => 'Sin City', :limit => 1)

Find a single movie by it’s TMDb ID:

@movie = TmdbMovie.find(:id => 187)

Find a single movie by it’s IMDB ID:

@movie = TmdbMovie.find(:imdb => 'tt0401792')

Find all cast members whose names match a given string:

@actors = TmdbCast.find(:name => 'Fred')

Find an individual cast member via their TMDb ID:

@actor = TmdbCast.find(:id => 101)

Get the info for a movie in French:

@movie = TmdbMovie.find(:title => 'Sin City', :limit => 1, :language => "fr")

Contributing¶ ↑

ruby-tmdb3 is maintained to work under Ruby 1.8.x & 1.9.x. Please make sure it works under both.

Fork the repo.
Create a topic branch.
Push the topic branch to your fork.
Create a pull request.

Item information¶ ↑

To find out more about the information each object offers on retrieved items have a look at the TMDb API Docs. For the most accurate information about the information available have a look at the data directly through ruby-tmdb3 by calling @item.raw_data.inspect

Author & Credits¶ ↑

Authors: Irio Irineu Musskopf Junior, Aaron Gough
Contributors: Alex Hayes, Alvaro Pereyra Rabanal, Linus Oleander, aristides, Robin Boutros, Loïc Guitaut

KellyMahan/ruby-tmdb