Add Watch Providers service with methods for movies and TV shows

Author: UweTrottmann

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Next version
 
 * Add TV season translations method by @laurentblue in https://github.com/UweTrottmann/tmdb-java/pull/108
+* Add Watch Providers service with methods for movies and TV shows.
 
 ## 2.12.0 - 2025-08-08
 

src/main/java/com/uwetrottmann/tmdb2/Tmdb.java

@@ -33,6 +33,7 @@
 import com.uwetrottmann.tmdb2.services.TvEpisodesService;
 import com.uwetrottmann.tmdb2.services.TvSeasonsService;
 import com.uwetrottmann.tmdb2.services.TvService;
+import com.uwetrottmann.tmdb2.services.WatchProvidersService;
 import java.io.IOException;
 import javax.annotation.Nullable;
 import okhttp3.Interceptor;
@@ -309,6 +310,14 @@ public DiscoverService discoverService() {
         return getRetrofit().create(DiscoverService.class);
     }
 
+    public DiscoverMovieBuilder discoverMovie() {
+        return new DiscoverMovieBuilder(discoverService());
+    }
+
+    public DiscoverTvBuilder discoverTv() {
+        return new DiscoverTvBuilder(discoverService());
+    }
+
     public FindService findService() {
         return getRetrofit().create(FindService.class);
     }
@@ -369,12 +378,8 @@ public TrendingService trendingService() {
         return getRetrofit().create(TrendingService.class);
     }
 
-    public DiscoverMovieBuilder discoverMovie() {
-        return new DiscoverMovieBuilder(discoverService());
-    }
-
-    public DiscoverTvBuilder discoverTv() {
-        return new DiscoverTvBuilder(discoverService());
+    public WatchProvidersService watchProvidersService() {
+        return getRetrofit().create(WatchProvidersService.class);
     }
 
 }

src/main/java/com/uwetrottmann/tmdb2/entities/WatchProvidersResults.java

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2025 Uwe Trottmann
+
+package com.uwetrottmann.tmdb2.entities;
+
+
+import java.util.List;
+
+public class WatchProvidersResults {
+
+    public List<WatchProviders.WatchProvider> results;
+
+}

src/main/java/com/uwetrottmann/tmdb2/services/WatchProvidersService.java

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2025 Uwe Trottmann
+
+package com.uwetrottmann.tmdb2.services;
+
+
+import com.uwetrottmann.tmdb2.entities.WatchProvidersResults;
+import retrofit2.Call;
+import retrofit2.http.GET;
+import retrofit2.http.Query;
+
+public interface WatchProvidersService {
+
+    /**
+     * See <a href="https://developer.themoviedb.org/reference/watch-providers-movie-list">Movie Providers</a>.
+     */
+    @GET("watch/providers/movie")
+    Call<WatchProvidersResults> movie(
+            @Query("language") String language,
+            @Query("watch_region") String watchRegion
+    );
+
+    /**
+     * See <a href="https://developer.themoviedb.org/reference/watch-provider-tv-list">TV Providers</a>.
+     */
+    @GET("watch/providers/tv")
+    Call<WatchProvidersResults> tv(
+            @Query("language") String language,
+            @Query("watch_region") String watchRegion
+    );
+
+}

src/test/java/com/uwetrottmann/tmdb2/assertions/GenericAssertions.java

@@ -22,6 +22,7 @@
 import com.uwetrottmann.tmdb2.entities.Videos;
 import com.uwetrottmann.tmdb2.entities.WatchProviders;
 import java.util.List;
+import java.util.Map;
 
 public class GenericAssertions {
 
@@ -50,6 +51,16 @@ public static void assertVideos(Videos videos) {
         }
     }
 
+    public static void assertWatchProviders(WatchProviders providers) {
+        assertThat(providers.results).isNotNull();
+        for (Map.Entry<String, WatchProviders.CountryInfo> entry : providers.results.entrySet()) {
+            assertThat(entry.getKey()).isNotEmpty();
+            WatchProviders.CountryInfo countryInfo = entry.getValue();
+            assertThat(countryInfo.link).isNotEmpty();
+            assertWatchProviderCountryInfo(countryInfo);
+        }
+    }
+
     public static void assertWatchProviderCountryInfo(WatchProviders.CountryInfo info) {
         assertWatchProviders(info.flatrate);
         assertWatchProviders(info.free);
@@ -58,7 +69,7 @@ public static void assertWatchProviderCountryInfo(WatchProviders.CountryInfo inf
         assertWatchProviders(info.rent);
     }
 
-    private static void assertWatchProviders(List<WatchProviders.WatchProvider> providers) {
+    public static void assertWatchProviders(List<WatchProviders.WatchProvider> providers) {
         for (WatchProviders.WatchProvider provider : providers) {
             assertThat(provider).isNotNull();
             assertThat(provider.display_priority).isGreaterThanOrEqualTo(0);

src/test/java/com/uwetrottmann/tmdb2/services/MoviesServiceTest.java

@@ -12,7 +12,7 @@
 import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertImages;
 import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertTranslations;
 import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertVideos;
-import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertWatchProviderCountryInfo;
+import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertWatchProviders;
 import static com.uwetrottmann.tmdb2.assertions.KeywordAssertions.assertKeywords;
 import static com.uwetrottmann.tmdb2.assertions.ListAssertions.assertListResultsPage;
 import static com.uwetrottmann.tmdb2.assertions.MovieAssertions.assertMovie;
@@ -43,7 +43,6 @@
 import com.uwetrottmann.tmdb2.enumerations.AppendToResponseItem;
 import java.io.IOException;
 import java.util.HashMap;
-import java.util.Map;
 import org.junit.Test;
 import retrofit2.Call;
 
@@ -238,21 +237,15 @@ public void test_videos() throws IOException {
 
     @Test
     public void watchProviders() throws IOException {
-        Call<WatchProviders> call = getUnauthenticatedInstance().moviesService().watchProviders(
-                testMovie.id
-        );
-
-        WatchProviders providers = call.execute().body();
+        WatchProviders providers = getUnauthenticatedInstance()
+                .moviesService()
+                .watchProviders(testMovie.id)
+                .execute()
+                .body();
 
         assertThat(providers).isNotNull();
+        assertWatchProviders(providers);
         assertThat(providers.id).isEqualTo(testMovie.id);
-        assertThat(providers.results).isNotNull();
-        for (Map.Entry<String, WatchProviders.CountryInfo> entry : providers.results.entrySet()) {
-            assertThat(entry.getKey()).isNotEmpty();
-            WatchProviders.CountryInfo countryInfo = entry.getValue();
-            assertThat(countryInfo.link).isNotEmpty();
-            assertWatchProviderCountryInfo(countryInfo);
-        }
     }
 
     @Test

src/test/java/com/uwetrottmann/tmdb2/services/TvServiceTest.java

@@ -13,7 +13,7 @@
 import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertImages;
 import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertTranslations;
 import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertVideos;
-import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertWatchProviderCountryInfo;
+import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertWatchProviders;
 import static com.uwetrottmann.tmdb2.assertions.KeywordAssertions.assertKeywords;
 import static com.uwetrottmann.tmdb2.assertions.TvAssertions.assertTvShow;
 import static com.uwetrottmann.tmdb2.assertions.TvAssertions.assertTvShowDataIntegrity;
@@ -43,7 +43,6 @@
 import com.uwetrottmann.tmdb2.enumerations.AppendToResponseItem;
 import java.io.IOException;
 import java.util.HashMap;
-import java.util.Map;
 import org.junit.Test;
 import retrofit2.Call;
 
@@ -295,21 +294,15 @@ public void test_videos() throws IOException {
 
     @Test
     public void watchProviders() throws IOException {
-        Call<WatchProviders> call = getUnauthenticatedInstance().tvService().watchProviders(
-                testTvShow.id
-        );
-
-        WatchProviders providers = call.execute().body();
+        WatchProviders providers = getUnauthenticatedInstance()
+                .tvService()
+                .watchProviders(testTvShow.id)
+                .execute()
+                .body();
 
         assertThat(providers).isNotNull();
         assertThat(providers.id).isEqualTo(testTvShow.id);
-        assertThat(providers.results).isNotNull();
-        for (Map.Entry<String, WatchProviders.CountryInfo> entry : providers.results.entrySet()) {
-            assertThat(entry.getKey()).isNotEmpty();
-            WatchProviders.CountryInfo countryInfo = entry.getValue();
-            assertThat(countryInfo.link).isNotEmpty();
-            assertWatchProviderCountryInfo(countryInfo);
-        }
+        assertWatchProviders(providers);
     }
 
     @Test

src/test/java/com/uwetrottmann/tmdb2/services/WatchProvidersServiceTest.java

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2025 Uwe Trottmann
+
+package com.uwetrottmann.tmdb2.services;
+
+
+import static com.uwetrottmann.tmdb2.assertions.GenericAssertions.assertWatchProviders;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.uwetrottmann.tmdb2.BaseTestCase;
+import com.uwetrottmann.tmdb2.entities.WatchProvidersResults;
+import java.io.IOException;
+import org.junit.Test;
+
+public class WatchProvidersServiceTest extends BaseTestCase {
+
+    @Test
+    public void movies() throws IOException {
+        WatchProvidersResults results = getUnauthenticatedInstance()
+                .watchProvidersService()
+                .movie(null, null)
+                .execute()
+                .body();
+        
+        assertThat(results).isNotNull();
+        assertThat(results.results).isNotEmpty();
+        assertWatchProviders(results.results);
+    }
+
+    @Test
+    public void tv() throws IOException {
+        WatchProvidersResults results = getUnauthenticatedInstance()
+                .watchProvidersService()
+                .tv(null, null)
+                .execute()
+                .body();
+
+        assertThat(results).isNotNull();
+        assertThat(results.results).isNotEmpty();
+        assertWatchProviders(results.results);
+    }
+}