This README is the one indexed from the repository at its latest ref, not from the tag for this version.

The Movie Database API

A Crystal wrapper for the The Movie Database API.

Installation

Add this lines to your shards.yml file:

dependencies:
  tmdb:
    github: mmacia/tmdb.cr
    branch: master

Then run shards install from your project.

Usage

Initial configuration

You have to provide your API key like this:

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

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 = Tmdb::FileCache.new("/tmp/tmdb", 10_000)
end

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
end

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"

Cast

Get the cast for a specific movie ID.

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

Crew

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.images

Movie keywords

Get the plot keywords for a specific movie ID.

movie = Tmdb::Movie.detail 24
movie.keywords

Movie trailers

Get the release trailers for a specific movie ID.

movie = Tmdb::Movie.detail 24
movie.videos

Movie releases

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

movie = Tmdb::Movie.detail 24
movie.release_dates

Upcoming movies

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

Tmdb::Movie.upcoming

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

Search for people by name.

Tmdb::Search.people "Paul"

Popular people

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

Tmdb::People.popular

Multi search

Search for movies, TV shows and people in a single request.

results = Tmdb::Search.multi "terminator"
results.each do |result|
  case result
  in Tmdb::MovieResult    then puts result.title
  in Tmdb::PersonResult   then puts result.name
  in Tmdb::Tv::ShowResult then puts result.name
  end
end

Endpoints

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

Missing endpoints:

• Account
• Authentication
• Guest Sessions
• Lists

Contributing

1. Fork it (https://github.com/your-github-user/tmdb/fork)
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

Contributors

• Moisès Macià - creator and maintainer