themoviedb.org

tmdb-java-client

A Java client to access The Movie Database
Maven Project Info - Javadoc
Report Bug - Request Feature

Table of Contents

1. About The Project
   • Current Unsupported Features
2. Usage
   • Getting Started
   • Recipes
3. Contributing
4. License
5. Contact

About The Project

A client for Java programmatic access to The Movie Database v3 API.

Current Unsupported Features

1. This client does not support v4 API for Account, Auth, and Lists APIs. This client only supports v3 at this time. Please file a feature request if your use-case requires these APIs.

(back to top)

Usage

Getting Started

1. Per the API documentation, you will need to obtain an API read access token in order to make requests to the service.

2. Instantiate the client with the read access token:

   Tmdb tmdb = new Tmdb("MyReadAccessToken");
   // Access APIs (e.g., MoviesApi)
   MoviesApi moviesApi = tmdb.getMoviesApi();

(back to top)

Recipes

Searching for content

SearchApi searchApi = tmdb.getSearchApi();
SearchMoviesResponse response = searchApi.searchMovies(
        SearchMoviesRequest.builder()
                .query("Harry Potter")
                .build());

// Alternatively, one can search for more than just movies
// where the response results can return Person, TV, and Movie
// based results.
SearchMultiResponse multiResponse = searchApi.searchMulti(
        SearchMultiRequest.builder()
                .query("Firefly")
                .build());

Discovering content with filters

Discovering content can optionally include filters. Some request filters define use of a delimited list of attributes. This can be defined through use of a FilterQueryBuilder

DiscoverMoviesRequest discoverMoviesRequest = DiscoverMoviesRequest.builder()
        .withReleaseType(String.valueOf(MovieReleaseType.DIGITAL.getType()))
        .watchRegionFilter(WatchRegionFilter.builder()
                .watchRegion(Locale.US.getCountry())
                .withWatchProviders(
                        // Include only Netflix (8) and Hulu (15)
                        // Watch Provider IDs can be obtained via the WatchProvidersApi
                        // This creates the String value of "8|15"
                        new FilterQueryBuilder<>(8, FilterQueryBuilder.Type.OR)
                                .append(15)
                                .build())
                .build())
        .build();
DiscoverMoviesResponse movieResponse = discoverApi.discoverMovies(movieRequest);

Creating a session to manage a user's account

AuthenticationApi authApi = tmdb.getAuthenticationApi();
AccountApi accountApi = tmdb.getAccountApi();

// Opens a browser to prompt the user to approve the new session.
SessionManager sessionManager = SessionManager.builder()
        .authApi(authApi)
        .config(RequestTokenGrantReceiver.Config.builder().build())
        .build();
// The sessionId can be persisted to prevent having to prompt the user
// every time a sessionId is required between application instances.
String sessionId = sessionManager.registerNewSession();

// Get the account identifier for the user
GetAccountDetailsResponse accountDetails = accountApi.getAccountDetailsForSession(
        GetAccountDetailsForSessionRequest.builder()
                .sessionId(sessionId)
                .build());
Integer accountId = accountDetails.getId();
  
// Manage the user's account and lists via AccountApi

// Either securely persist the user session ID for future use, 
// or you can delete the session.
sessionManager.deleteSession();

Customizing the HTTP client configuration

OkHttpClientBuilder example

If your use-case requires configuring the underlying OkHttpClient instance (e.g., configuring your own SSL cert verification, proxy, and/or connection timeouts), you can configure the client with the provided OkHttpClientBuilder, or alternatively with OkHttp's builder.

OkHttpClient httpClient = OkHttpClientBuilder.builder()
        .trustManager(myX509TrustManager) // Custom trust manager for self/internally signed SSL/TLS certs
        .hostnameVerifier(myHostnameVerifier) // Custom hostname verification for SSL/TLS endpoints
        .proxy(myProxy, myProxyUsername, myProxyPassword) // Proxy config
        .connectTimeout(8000L) // connection timeout in milliseconds
        .readTimeout(5000L) // read timeout in milliseconds
        .writeTimeout(5000L) // write timeout in milliseconds
        .build();
Connection connection = Connection.builder()
        .httpClient(httpClient)
        .gsonFactory(GsonFactory.getInstance())
        .readAccessToken("MyReadAccessToken")
        .build();
Tmdb tmdb = new Tmdb(connection);

(back to top)

Contributing

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/MyFeature)
3. Commit your Changes (git commit -m 'Add my feature')
4. Push to the Branch (git push origin feature/MyFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the GPLv3 license. See LICENSE for more information.

(back to top)

Contact

Andy Miles - andy.miles (at) amilesend.com

Project Link: https://github.com/andy-miles/tmdb-java-client

(back to top)