This library provides a Java-wrapper around the JSON API provided by TMdB, which is an open database for movie and tv content.
The wrapper implements most, if not all, of the JSON API. However, because the API is subject to constantly change, new functionality may not be implemented, or current functionality may break. Please point this out by submitting an issue, or even better, just send us a pull request!
It's available via Maven Central. Just add it as dependency to your project.
Maven
<dependency>
<groupId>uk.co.conoregan</groupId>
<artifactId>themoviedbapi</artifactId>
<version>{version}</version>
</dependency>
Gradle (Kotlin)
dependencies {
implementation("uk.co.conoregan:themoviedbapi:{version}")
}
To register for a TMdB API key, click the API link from within your account settings page.
With this you can instantiate info.movito.themoviedbapi.TmdbApi
, which has getters for all subcategories of the API, e.g.
TmdbApi tmdbApi = new TmdbApi("<apikey>");
TmdbMovies tmdbMovies = tmdbApi.getMovies();
MovieDb movie = tmdbMovies.getDetails(5353, "en-US");
Some of the API methods support appending additional requests to the response. This concept is part of the underlying TMdB API - Append To Response, our wrapper just mimics the scheme.
If you try to call the getter for a model that has fields for appendable responses, without providing the append to response parameter to
the function, it will return null
.
TmdbMovies tmdbMovies = tmdbApi.getMovies();
MovieDb movie = tmdbMovies.getDetails(5353, "en-US");
Images images = movie.getImages(); // this will be null
MovieDb movie = tmdbMovies.getDetails(5353, "en-US", MovieAppendToResponse.IMAGES);
Images images = movie.getImages(); // this will NOT be null
You can also append multiple responses to the same request by providing multiple append to response values.
TmdbMovies tmdbMovies = tmdbApi.getMovies();
MovieDb movie = tmdbMovies.getDetails(5353, "en-US", MovieAppendToResponse.IMAGES, MovieAppendToResponse.VIDEOS);
MovieDb movie = tmdbMovies.getDetails(5353, "en-US", MovieAppendToResponse.values());
To find all methods that use append to response, see the info.movito.themoviedbapi.tools.appendtoresponse.AppendToResponse
interface
implementations.
Every API method can throw a info.movito.themoviedbapi.tools.TmdbException
if the request fails for any reason. You should catch this
exception and handle it appropriately.
Some exceptions are caused because the response status provided by the TMdB API is not successful. To see more details, see the
info.movito.themoviedbapi.tools.TmdbResponseCode
and TMdB Errors.
In the example below, the response was successful, but response code returned by TMdB API was not successful due to an authentication failure.
TmdbMovies tmdbMovies = tmdbApi.getMovies();
try {
AccountStates accountStates = tmdbMovies.getAccountStates(-1, "accountId", null);
}
catch (TmdbResponseException exception) {
TmdbResponseCode responseCode = exception.getResponseCode();
// handle unsuccessful TMdB response code
}
catch (TmdbException exception) {
// handle unknown-cause exception
}
We chose to throw exceptions rather than returning null
, so you have more control over what you do with each failure case. E.g. with the
example above, you may want to display an error message to the user about failing authentication.
This project uses SLF4J to abstract the logging in the project. To use the logging in your own project you should add one of the provided adapter bindings.
Model classes are placed under info.movito.themoviedbapi.model
package. Add this to proguard-rules.pro
so that, these classes can
survive minification.
-keep class info.movito.themoviedbapi.model.** { *; }
The library was developed for Movito to interact with TMdB services. This library has been inspired by api-themoviedb but has been rewritten to provide a more open license, a more clean API, and to expose more features of the TMdB JSON API.