The Movie DB (TMDb) api wrapper movie-database-api tmdb api-client
0.2.1 Latest release released

The Movie Database API

A Crystal wrapper for the The Movie Database API.



Add this lines to your shards.yml file:

    github: mmacia/
    branch: master

Then run shards install from your project.


Initial configuration

You have to provide your API key like this:

Tmdb.configure do |conf|
  conf.api_key = "secret"
  conf.default_language = "en"

You can also set the API key in environment variable TMDB_API_KEY. The value of this variable has higher precedence.

$ export TMDB_API_KEY='secret'

The default language is english, but you can temporarily override the global language for a single request by specifying it as an additional parameter:

# example
Tmdb::Search.movies("terminator", language: "es")

You can save a few API calls activating the cache:

Tmdb.configure do |conf|
  conf.cache ="/tmp/tmdb", 10_000)

If you active cache, all methods will be using it. Sometimes you want to get fresh data for some particular requests: you can pass the skip_cache: true to disable cache.

movies = Tmdb::Movie.popular skip_cache: true

Paginated resources are managed by LazyIterator(T) class. This acts as a infinite iterator, you just have to call #each, #select, #map or whatever enumerable method to acces to the whole collection without worrying about pagination.

# example
movies = Tmdb::Search.movies("terminator")

pp movies.total_items

movies.each do |m|
  pp m.original_title

Get a movie by ID

Get the movie information for specific movie ID.

Tmdb::Movie.detail 24

Tmdb::Movie.detail 24, language: "es"

Search movies

Search movies by title.

Tmdb::Search.movies "terminator"

Search movies by title and release year.

Tmdb::Search.movies "terminator", year: 1984

Alternative titles

Get the alternative titles for a specific movie.

movie = Tmdb::Movie.detail 24
movie.alternative_titles country: "es"


Get the cast for a specific movie ID.

movie = Tmdb::Movie.detail 24
movie.cast language: "it"


Get the crew for a specific movie ID.

movie = Tmdb::Movie.detail 24
movie.cast language: "de"

Movie images

Get the images (posters and backdrops) for a specific movie ID.

movie = Tmdb::Movie.detail 24

Movie keywords

Get the plot keywords for a specific movie ID.

movie = Tmdb::Movie.detail 24

Movie trailers

Get the release trailers for a specific movie ID.

movie = Tmdb::Movie.detail 24

Movie releases

Get the release dates by country for a specific movie ID.

movie = Tmdb::Movie.detail 24

Upcoming movies

Get the list of upcoming movies. This list refreshes every day.


You can get the upcoming movie for a region.

Tmdb::Movie.upcoming region: "pt"

Find a person by ID

Get the basic person information for a specific person ID.

Tmdb::Person.detail 138

Search people

Seach for people by name.

Tmdb::Search.people "Paul"

Popular people

Gets a list of popular people. This list refreshes every day.



All endpoints available are those listed in The Movie Database API documentation.

Missing endpoints:

  • Account
  • Authentication
  • Guest Sessions
  • Lists
  • Multi search


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


  github: mmacia/
  version: ~> 0.2.1
License MIT
Crystal 1.6.0


Dependencies 0

Development Dependencies 2

  • ameba ~> 1.1.0
    {'github' => 'crystal-ameba/ameba', 'version' => '~> 1.1.0'}
  • vcr 0.5.3
    {'github' => 'spoved/', 'version' => '0.5.3'}

Dependents 0

Last synced .
search fire star recently