Add filtering by release year and object type

Author: Electronic-Mango

src/simplejustwatchapi/justwatch.py

@@ -79,6 +79,9 @@ def search(
     best_only: bool = True,
     offset: int = 0,
     providers: list[str] | str | None = None,
+    min_year: int | None = None,
+    max_year: int | None = None,
+    object_types: list[str] | str | None = None,
 ) -> list[MediaEntry]:
     """
     Search JustWatch for the given title.
@@ -148,6 +151,18 @@ def search(
             You can look up values through [`providers`]
             [simplejustwatchapi.justwatch.providers] function.
 
+        min_year (int | None): Minimum release year of returned titles.
+            If `None` (the default value), no filtering is done.
+
+        max_year (int | None): Maximum release year of returned titles.
+            If `None` (the default value), no filtering is done.
+
+        object_types (list[str] | str | None): Types of objects to filter for, it seems
+            that only `SHOW` and `MOVIE` are useful, but it's not strictly enforced.
+            Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used but they seem to
+            return shows, the same as `SHOW` type. If `None` (the default value), no
+            filtering is done.
+
     Returns:
         (list[MediaEntry]): List of tuples with details of search results.
 
@@ -159,7 +174,16 @@ def search(
 
     """
     request = prepare_search_request(
-        title, country, language, count, best_only, offset, providers
+        title,
+        country,
+        language,
+        count,
+        best_only,
+        offset,
+        providers,
+        min_year,
+        max_year,
+        object_types,
     )
     response = _post_to_jw_graphql_api(request)
     return parse_search_response(response)
@@ -172,6 +196,9 @@ def popular(
     best_only: bool = True,
     offset: int = 0,
     providers: list[str] | str | None = None,
+    min_year: int | None = None,
+    max_year: int | None = None,
+    object_types: list[str] | str | None = None,
 ) -> list[MediaEntry]:
     """
     Look up all currently popular titles on JustWatch.
@@ -233,6 +260,18 @@ def popular(
             You can look up values through [`providers`]
             [simplejustwatchapi.justwatch.providers] function.
 
+        min_year (int | None): Minimum release year of returned titles.
+            If `None` (the default value), no filtering is done.
+
+        max_year (int | None): Maximum release year of returned titles.
+            If `None` (the default value), no filtering is done.
+
+        object_types (list[str] | str | None): Types of objects to filter for, it seems
+            that only `SHOW` and `MOVIE` are useful, but it's not strictly enforced.
+            Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used but they seem to
+            return shows, the same as `SHOW` type. If `None` (the default value), no
+            filtering is done.
+
     Returns:
         (list[MediaEntry]): List of tuples with details of popular titles.
 
@@ -244,7 +283,15 @@ def popular(
 
     """
     request = prepare_popular_request(
-        country, language, count, best_only, offset, providers
+        country,
+        language,
+        count,
+        best_only,
+        offset,
+        providers,
+        min_year,
+        max_year,
+        object_types,
     )
     response = _post_to_jw_graphql_api(request)
     return parse_popular_response(response)

src/simplejustwatchapi/query.py

@@ -44,6 +44,9 @@ def prepare_search_request(
     best_only: bool,
     offset: int,
     providers: list[str] | str | None,
+    min_year: int | None,
+    max_year: int | None,
+    object_types: list[str] | str | None,
 ) -> dict[str, Any]:
     """
     Prepare search request for JustWatch GraphQL API.
@@ -66,6 +69,10 @@ def prepare_search_request(
         offset (int): Search results offset.
         providers (list[str] | str | None): 3-letter service identifier(s),
             or `None` for all providers.
+        min_year (int | None): Minimum release year of returned titles.
+        max_year (int | None): Maximum release year of returned titles.
+        object_types (list[str] | str | None): Types of objects to filter for, it seems
+            that only "SHOW" and "MOVIE" make sense.
 
     Returns:
         (dict[str, Any]): JSON with GraphQL POST body.
@@ -75,7 +82,11 @@ def prepare_search_request(
         "operationName": "GetSearchTitles",
         "variables": {
             "first": count,
-            "searchTitlesFilter": {"searchQuery": title, "packages": providers},
+            "searchTitlesFilter": {
+                "searchQuery": title,
+                "packages": providers,
+                **_list_variables(min_year, max_year, object_types),
+            },
             **_common_variables(best_only),
             **_locale_variables(country, language),
             "offset": offset or None,
@@ -118,6 +129,9 @@ def prepare_popular_request(
     best_only: bool,
     offset: int,
     providers: list[str] | str | None,
+    min_year: int | None,
+    max_year: int | None,
+    object_types: list[str] | str | None,
 ) -> dict[str, Any]:
     """
     Prepare "get popular" request for JustWatch GraphQL API.
@@ -139,6 +153,10 @@ def prepare_popular_request(
         offset (int): Search results offset.
         providers (list[str] | str | None): 3-letter service identifier(s),
             or `None` for all providers.
+        min_year (int | None): Minimum release year of returned titles.
+        max_year (int | None): Maximum release year of returned titles.
+        object_types (list[str] | str | None): Types of objects to filter for, it seems
+            that only "SHOW" and "MOVIE" make sense.
 
     Returns:
         (dict[str, Any]): JSON with GraphQL POST body.
@@ -148,7 +166,10 @@ def prepare_popular_request(
         "operationName": "GetPopularTitles",
         "variables": {
             "first": count,
-            "popularTitlesFilter": {"packages": providers},
+            "popularTitlesFilter": {
+                "packages": providers,
+                **_list_variables(min_year, max_year, object_types),
+            },
             **_common_variables(best_only),
             **_locale_variables(country, language),
             "offset": offset or None,
@@ -507,6 +528,16 @@ def _locale_variables(country: str, language: str) -> dict[str, str]:
     return {"country": country.upper(), "language": language}
 
 
+def _list_variables(
+    min_year: int | None, max_year: int | None, object_types: list[str] | str | None
+) -> dict[str, Any]:
+    """Return dict with variables related to looking up lists of titles."""
+    return {
+        "objectTypes": object_types,
+        "releaseYear": {"min": min_year, "max": max_year},
+    }
+
+
 def _raise_for_errors_in_response(json: dict[str, Any]) -> None:
     """Raise JustWatchApiError if given JSON contains `errors` key."""
     if "errors" in json: