Neo TMDb

Dependency Status

Neo TMDb is a Ruby wrapper for the v3 TMDb API from It provides read-only access with caching and fault tolerance.


Currently you can find people by their TMDb id or search for people.

require 'neo-tmdb'

TMDb.configure do |config|
  # You must configure this library with a TMDb API key before you can use it.
  config.api_key = 'my-tmdb-api-key-here'

person = TMDb::Person.find(6384)
puts "#{}, born #{person.birthday} in #{person.place_of_birth}"
# => Keanu Reeves, born 1964-09-02 in Beirut, Lebanon

smallest = TMDb.configuration.image_profile_sizes.first
puts person.profile_image_url(smallest)
# =>

# Note: Only the first 20 results are returned.
people = TMDb::Person.where(:name => 'Reeves')
people.each do |person|
  # Note: Only attributes available in the search API will be populated here.
  puts "#{} has TMDb id #{}"

Configure caching

You can configure caching so that duplicate requests for the same person are read from the cache rather than directly from the TMDb servers. This helps improve the performance of you application but also prevents it from exceeding the API request limits on the TMDb servers.

require 'active_support'
require 'benchmark'
require 'neo-tmdb'

TMDb.configure do |config|
  config.api_key = 'my-tmdb-api-key-here'
  # You should configure your cache to expire entries after an appropriate
  # period. Note that MemoryStore may not be the best choice for your
  # application.
  config.cache =

# Note in the following how the first request takes considerable longer than
# the subsequent cached requests.
100.times do |n|
  Benchmark.benchmark('find ') do |b| do
      person = TMDb::Person.find(6384)
      puts "  #{} load #{n}"

You can use any cache that implements ActiveSupport's Cache interface.


Further documentation can be found in the feature files and on


  • Source hosted on GitHub.
  • Report issues on GitHub Issues.
  • Pull requests are very welcome! Please include scenario and spec coverage for every patch and create a topic branch for every separate change you make.
  • Tests are run by the defaults rake task.


See LICENSE for details.