TheMovieDB API

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}")
}

Usage

To register for a TMdB API key, click the API link from within your account settings page. There are two types of API keys currently provided by TMdB, please ensure you are using the API Read Access Token key.

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>");

Examples

Get movie details

TmdbMovies tmdbMovies = tmdbApi.getMovies();
MovieDb movie = tmdbMovies.getDetails(5353, "en-US");

Append to response

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.

Exception Handling

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.

Project Logging

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.

Prooguard / R8 rules

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.** { *; }

Notes & Acknowledgements

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.