Update documentation with new filtering options

Author: Electronic-Mango

docs/caveats.md

@@ -296,3 +296,20 @@ popular_results = popular("US", providers=list(name_to_code_dict.values()))
 !!! tip "When this actually might be useful"
     This only makes sense if you are already using other functions. To get **just** the
     codes use the [`providers`](#providers-function) function instead.
+
+
+
+## Filtering by type
+
+Functions [`search`](#search-for-a-title) and [`popular`](#popular-titles) allow for
+filtering of returned entries by "types". The types are list of strings (or just a single
+string), like `SHOW`, `MOVIE`. You can check
+[`examples/`](https://github.com/Electronic-Mango/simple-justwatch-python-api/tree/main/examples)
+for field `object_type`, however the only "useful" ones seem `SHOW` and `MOVIE`. You can
+use types like `SHOW_EPISODE`, or `SHOW_SEASON`, however they seem to default to "TV
+shows" - the same as for type `SHOW`.
+
+!!! warning "Types are not enforced, but must be valid"
+    While possible types are not enforced by functions in this API, they still **must**
+    be valid types in JustWatch API. Using unexpected type will result in HTTP error with
+    code 422.

docs/usage.md

@@ -502,3 +502,29 @@ while results := popular(count=page, offset=i):
     this method. Check
     [Maximum number of entries](caveats.md#maximum-number-of-entries) page for more
     details.
+
+
+
+### Additional filtering in [`search`](#search-for-a-title) and [`popular`](#popular-titles)
+
+[`search`](#search-for-a-title) and [`popular`](#popular-titles) functions allow for
+additional filtering of returned entries.
+
+| Field | Description |
+| ------| ----------- |
+| `object_types` | Types like `SHOW` or `MOVIE`. Values are not enforced, but types like `SHOW_EPISODE` or `SHOW_SEASON` return shows anyway; like `SHOW`. While not enforced they **must** be valid types. It can be either a list of strings, or a single string. |
+| `min_year` | Minimum release year. |
+| `max_year` | Maximum release year. |
+
+All filters are optional; when not configured (or set to `None`) the filtering is disabled.
+
+```python
+from simplejustwatchapi import popular, search
+
+# Get only currently popular TV shows:
+popular_shows = popular(object_types=["SHOW"])
+
+# Search for movies between 1990 and 2010:
+movies = search("The Matrix", min_year=1990, max_year=2010, object_types="MOVIE")
+# object_types with single element can be either a list, or just a string.
+```

src/simplejustwatchapi/justwatch.py

@@ -34,7 +34,13 @@
 | `providers` | Providers (like Netflix, Amazon Prime Video) for which offers should \
                 returned. Requires 3-letter "short name". Check \
                 [`providers`][simplejustwatchapi.justwatch.providers] for an example \
-                of how you can get that value.
+                of how you can get that value. |
+| `min_year` | Minimum release year of returned titles. |
+| `max_year` | Maximum release year of returned titles. |
+| `object_types` | 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. |
 
 Each function can raise two exceptions: