Skip to content

Commit 18dd288

Browse files
Electronic-MangoElectronic-Mango
committed
Update README.md
1 parent 026a185 commit 18dd288

2 files changed

Lines changed: 217 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 215 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -53,20 +53,24 @@ Example outputs from all functions are in [`examples/`](examples/) directory.
5353
Search functions allows for searching entries based on a given title.
5454

5555
```python
56-
from simplejustwatchapi.justwatch import search
56+
from simplejustwatchapi import search
5757

58-
results = search("title", "US", "en", 5, True)
58+
results = search("title", "US", "en", 5, True, 0, {"nfx", "apv"})
5959
```
6060

6161
Only the first argument is required, it specifies a title to search.
6262

63-
| | Argument | Type | Required | Default value | Description |
64-
|---|-------------|--------|----------|---------------|--------------------------------------------------------|
65-
| 1 | `title` | `str` | **YES** | - | Title to look up |
66-
| 2 | `country` | `str` | NO | `"US"` | Country to search for offers |
67-
| 3 | `language` | `str` | NO | `"en"` | Language of responses |
68-
| 4 | `count` | `int` | NO | `4` | Up to how many entries should be returned |
69-
| 5 | `best_only` | `bool` | NO | `True` | Determines whether only best offers should be returned |
63+
| | Argument | Type | Required | Default value | Description |
64+
|---|-------------|--------|----------|---------------------|--------------------------------------------------------|
65+
| 1 | `title` | `str` | **YES** | - | Title to look up |
66+
| 2 | `country` | `str` | NO | `"US"` | Country to search for offers |
67+
| 3 | `language` | `str` | NO | `"en"` | Language of responses |
68+
| 4 | `count` | `int` | NO | `4` | Up to how many entries should be returned |
69+
| 5 | `best_only` | `bool` | NO | `True` | Determines whether only best offers should be returned |
70+
| 6 | `offset` | `int` | NO | `0` | How many titles should be skipped from the output |
71+
| 7 | `providers` | `list[str] \| str \| None`| NO | `None` | Determines whether only best offers should be returned |
72+
73+
`title` is just a string to look up.
7074

7175
`country` must be **ISO 3166-1 alpha-2** 2-letter code , e.g. `US`, `GB`, `FR`.
7276
It should be uppercase, however lowercase codes are automatically converted to uppercase.
@@ -79,13 +83,77 @@ If JustWatch GraphQL API returns fewer entries, then this function will also ret
7983
`best_only` determines whether similar offers, but lower quality should be included in response.
8084
If a platform offers streaming for a given entry in 4K, HD and SD, then `best_only = True` will return only the 4K offer, `best_only = False` will return all three.
8185

86+
`offset` allows for very basic pagination, letting you get more data without running into [request complexity](#request-complexity).
87+
It simply skips `offset` number of first entries (on the API side, nothing is done inside the library).
88+
Since there is no session there's no guarantee of results "stability" - if JustWatch decides to
89+
shuffle returned values (I'm not sure what would be the reason, but in theory it's possible)
90+
you might get repeats, or missing entries. It's also not possible to get **all** the data,
91+
only up to 1999, check [Maximum number of entries](#maximum-number-of-entries) for details.
92+
93+
`providers` is a selection of (usually) **3-letter** identifiers for a service provider ("Netflix", "Amazon Prime Video", etc.).
94+
It can be either a list, or (for single providers) a string.
95+
`None` (used as default) turns off any filtering based on providers.
96+
You can get the possible values through [`providers`](#providers) function and `short_name` field from returned `OfferPackage` NamedTuples,
97+
or check [Provider codes](#provider-codes) for more details.
98+
8299
Returned value is a list of [`MediaEntry`](#return-data-structures) objects.
83100

84101
For very large searches (high `count` value) I recommend using default `best_only=True` to avoid issues with [request complexity](#request-complexity).
85102

86103
Example function call and its output is in [`examples/search_output.py`](examples/search_output.py).
87104

88105

106+
### Popular
107+
Look up all currently popular titles.
108+
The usage and output will be similar to [`search`](#search), function without any titles specified.
109+
110+
```python
111+
from simplejustwatchapi import popular
112+
113+
results = popular("US", "en", 5, True, 0, {"nfx", "apv"})
114+
```
115+
116+
No arguments are required.
117+
118+
| | Argument | Type | Required | Default value | Description |
119+
|---|-------------|--------|----------|---------------------|--------------------------------------------------------|
120+
| 1 | `country` | `str` | NO | `"US"` | Country to search for titles |
121+
| 2 | `language` | `str` | NO | `"en"` | Language of responses |
122+
| 3 | `count` | `int` | NO | `4` | Up to how many entries should be returned |
123+
| 4 | `best_only` | `bool` | NO | `True` | Determines whether only best offers should be returned |
124+
| 5 | `offset` | `int` | NO | `0` | How many titles should be skipped from the output |
125+
| 6 | `providers` | `list[str] \| str \| None`| NO | `None` | Determines whether only best offers should be returned |
126+
127+
`country` must be **ISO 3166-1 alpha-2** 2-letter code , e.g. `US`, `GB`, `FR`.
128+
It should be uppercase, however lowercase codes are automatically converted to uppercase.
129+
130+
`language` is a **ISO 639-1** (usually) 2-letter code, lowercase, e.g. `en`, `fr`.
131+
132+
`count` determines **up to** how many entries should be returned.
133+
If JustWatch GraphQL API returns fewer entries, then this function will also return fewer values.
134+
135+
`best_only` determines whether similar offers, but lower quality should be included in response.
136+
If a platform offers streaming for a given entry in 4K, HD and SD, then `best_only = True` will return only the 4K offer, `best_only = False` will return all three.
137+
138+
`offset` allows for very basic pagination letting you get more data without running into [request complexity](#request-complexity).
139+
It simply skips first entries (on the API side, nothing is done inside the library).
140+
Since there is no session there's no guarantee of results "stability" - if JustWatch decides to
141+
shuffle returned values (I'm not sure what would be the reason, but in theory it's possible)
142+
you might get repeats, or missing entries. It's also not possible to get **all** the data,
143+
only up to 2000, check [Maximum number of entries](#maximum-number-of-entries) for details.
144+
145+
`providers` is a selection of (usually) **3-letter** identifiers for a service provider ("Netflix", "Amazon Prime Video", etc.).
146+
It can be either a list, or (for single providers) a string.
147+
`None` (used as default) turns off any filtering based on providers.
148+
You can get the possible values through [`providers`](#providers) function and `short_name` field from returned `OfferPackage` NamedTuples,
149+
or check [Provider codes](#provider-codes) for more details.
150+
151+
Returned value is a list of [`MediaEntry`](#return-data-structures) objects.
152+
153+
For very large searches (high `count` value) I recommend using default `best_only=True` to avoid issues with [request complexity](#request-complexity).
154+
155+
Example function call and its output is in [`examples/popular_output.py`](examples/popular_output.py).
156+
89157
### Details
90158

91159
Details function allows for looking up details for a single entry via its node ID.
@@ -99,7 +167,7 @@ If you want to get seasons/episodes you can use the ID from [`search`](#search)
99167

100168
Usage is similar to [`search`](#search) function, just without `count` argument:
101169
```python
102-
from simplejustwatchapi.justwatch import details
170+
from simplejustwatchapi import details
103171

104172
results = details("nodeID", "US", "en", False)
105173
```
@@ -140,7 +208,7 @@ Each season contains similar data to the [`details`](#details) function, with ad
140208

141209
Usage also matches [`details`](#details) function:
142210
```python
143-
from simplejustwatchapi.justwatch import seasons
211+
from simplejustwatchapi import seasons
144212

145213
results = seasons("nodeID", "US", "en", False)
146214
```
@@ -164,7 +232,7 @@ Node/season ID can be taken from output of the [`seasons`](#seasons) function.
164232

165233
Usage matches [`details`](#details) function:
166234
```python
167-
from simplejustwatchapi.justwatch import seasons
235+
from simplejustwatchapi import seasons
168236

169237
results = seasons("nodeID", "US", "en", False)
170238
```
@@ -190,7 +258,7 @@ It allows specifying a set of countries, instead of a single one.
190258
This way you can simultaneously look up offers for multiple countries.
191259

192260
```python
193-
from simplejustwatchapi.justwatch import offers_for_countries
261+
from simplejustwatchapi import offers_for_countries
194262

195263
results = offers_for_countries("nodeID", {"US", "UK", "CA"}, "en", True)
196264
```
@@ -211,8 +279,35 @@ Returned value `dict[str, list[Offer]]`, where key is country given as argument
211279
Example function call and its output is in [`examples/offers_for_countries_output.py`](examples/offers_for_countries_output.py).
212280

213281

282+
### Providers
283+
284+
Get all available service providers ("Netflix", "Amazon Prime Video, etc.) for a given country.
214285

215-
## Return data structures
286+
```python
287+
from simplejustwatchapi import providers
288+
289+
results = providers("US")
290+
```
291+
292+
| | Argument | Type | Required | Default value | Description |
293+
|---|-------------|--------|----------|---------------|---------------------------------|
294+
| 1 | `country` | `str` | NO | `"US"` | Country to search for providers |
295+
296+
`country` must be **ISO 3166-1 alpha-2** 2-letter code , e.g. `US`, `GB`, `FR`.
297+
It should be uppercase, however lowercase codes are automatically converted to uppercase.
298+
299+
Returned value is a list of `OfferPackage` tuples.
300+
Initially they were meant to be used for `Offer` in `MediaEntry`/`Episode`, however the data structure
301+
matches output here, so it's reused.
302+
303+
You can use this function to get values for providers for [`search`](#search) and [`popular`](#popular) functions,
304+
the `short_name` field in returned `OfferPackage` tuples is the exact 3-letter code needed there.
305+
306+
Example function call and its output is in [`examples/providers_output.py`](examples/providers_output.py).
307+
308+
309+
310+
## Data structures
216311

217312
Detailed descriptions of all used data structures are available in the [documentation](https://electronic-mango.github.io/simple-justwatch-python-api/simplejustwatchapi.html#module-simplejustwatchapi.query).
218313

@@ -259,6 +354,112 @@ Using `best_only=True` should alleviate the issue somewhat, so for very large re
259354

260355

261356

357+
## Maximum number of entries
358+
359+
The JustWatch API itself won't allow for getting more than 1999 entries, through `count` and `offset`, regardless of request complexity.
360+
If you try to get the 2000th entry the API (and functions in this libary) will return an empty list.
361+
362+
**If you try to access over the 1999th entry you won't get *up to* 1999 entries, you'll get an empty list.**
363+
364+
For example, this will get you entries 1990 - 1999 - a 9 element list of `MediaEntry`, as expected:
365+
366+
```python
367+
from simplejustwatchapi import search
368+
369+
results = search("title", count=9, offset=1990)
370+
# len(results) == 9, as expected
371+
```
372+
373+
But trying to get 1990 - 2000 will result in an empty list:
374+
375+
```python
376+
from simplejustwatchapi import search
377+
378+
results = search("title", count=10, offset=1990)
379+
# len(results) == 0, API responded with empty list
380+
```
381+
382+
Overshooting will also result in an empty list:
383+
384+
```python
385+
from simplejustwatchapi import search
386+
387+
results = search("title", count=100, offset=1950)
388+
# len(results) == 0, API responded with empty list
389+
```
390+
391+
Interestingly, you'll still hit [too high request complexity](#request-complexity)
392+
for too high values of `count`, even though you'd get an empty list anyway:
393+
394+
```python
395+
from simplejustwatchapi import search
396+
397+
results = search("title", count=200, offset=1950)
398+
# Errors out due to complexity
399+
```
400+
401+
402+
403+
## Provider codes
404+
405+
One note to keep in mind - the codes can be different for different countries.
406+
407+
408+
### [`providers`](#providers) function
409+
410+
The easiest way of getting all provider codes for filtering in [`search`](#search) and [`popular`](#popular) functions
411+
is through [`providers`](#providers) function, for example:
412+
413+
```python
414+
from simplejustwatchapi import popular, providers
415+
416+
codes = [
417+
package.short_name
418+
for package
419+
in providers("GB") # Look up all providers in the UK.
420+
if package.name in ("Netflix", "Amazon Prime Video") # Only get codes for specific providers
421+
]
422+
423+
# codes == ["nfx", "amp"]
424+
425+
# Get popular titles only for selected providers:
426+
popular_netflix_amazon = popular(providers=codes)
427+
```
428+
429+
430+
### Query parameters from JustWatch
431+
432+
You can also get them by going to [JustWatch main page](https://www.justwatch.com/)
433+
and selecting **at least 2** of available services.
434+
**You need 2**, for 1 you'll get its full name.
435+
Only for multiple you'll get the needed codes as `?providers=<code1>+<code2>+...` query parameter,
436+
for example on US version the URL when selecting "Netflix" and "Amazon Prime Video" is:
437+
438+
```url
439+
https://www.justwatch.com/us?providers=nfx,prv
440+
```
441+
442+
So the codes for them are `nfx` and `prv` for the US.
443+
444+
445+
### Stored output from other commands with offers
446+
447+
The codes are also returned when looking up offers (through pretty much any function aside from `providers`) through `OfferPackage` and its `short_name` field.
448+
For example, to get a `dict` "**full name**": "**code**" you can:
449+
450+
```python
451+
from simplejustwatchapi import search
452+
453+
results = search("title", "US", "en", 5, True)
454+
name_to_code_dict = {
455+
offer.package.name: offer.package.short_name # Get name and short_name/code from packages
456+
for entry in results # Iterate all entries
457+
for offer in entry.offers # Iterate all offers per entry
458+
}
459+
```
460+
461+
462+
262463
## Disclaimer
263464

264465
This API is in no way affiliated, associated, authorized, endorsed by, or in any way officially connected with JustWatch.

‎src/simplejustwatchapi/justwatch.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -287,12 +287,12 @@ def offers_for_countries(
287287
return parse_offers_for_countries_response(response.json(), countries)
288288

289289

290-
def providers(country: str) -> list[OfferPackage]:
290+
def providers(country: str = "US") -> list[OfferPackage]:
291291
"""
292292
Look up all providers for the given country code.
293293
294294
Args:
295-
country (str): 2-letter country code.
295+
country (str): 2-letter country code, ``US`` by default.
296296
297297
Returns:
298298
list[OfferPackage]: List of all found providers. ``OfferPackage`` tuple matches

0 commit comments

Comments
 (0)