ruby-tmdb is an ActiveRecord-style API wrapper for (TMDb). ruby-tmdb is designed to make common tasks much easier than they would be if dealing directly with the URL based API.


gem install ruby-tmdb


require 'rubygems'
require 'ruby-tmdb'

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

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

# => 12
# => [binary blob representing JPEG]


ruby-tmdb provides 2 main objects that you will use to query the API


These objects provide access to movie and cast listing respectively.

Each object provides a find() method which accepts a number of options:

TmdbMovie.find(:id => 123, :title => "fight club", :imdb => 'tt0401792', :limit => 10, :expand_results => true)

specifies an individual movie via it's TMDb id


specifies a query string to look for in the movie titles


specifies an idividual movie via it's IMDB id


specifies the maximum number of results to be returned


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-tmdb 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'.

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

specifies an idividual cast member via their TMDb id


specifies a query string to look for in the cast names


see TmdbMovie


see TmdbMovie

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)

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-tmdb by calling @item.raw_data.inspect

Author & Credits


Aaron Gough

Copyright © 2010 Aaron Gough (, released under the MIT license