A simple unofficial JustWatch Python API which uses GraphQL to access JustWatch data, built with httpx and Python3.11.
Project is available in PyPi:
pip install simple-justwatch-python-apiThis Python API has 3 functions:
search- search for entries based on titledetails- get details for entry based on its node IDoffers_for_countries- get offers for entry based on its node ID, can look for offers in multiple countries
Detailed documentation is available in https://electronic-mango.github.io/simple-justwatch-python-api/.
Example outputs from all commands are in examples/ directory.
Search functions allows for searching entries based on a given title.
from simplejustwatchapi.justwatch import search
results = search("title", "US", "en", 5, True)Only the first argument is required, it specifies a title to search.
| Argument | Type | Required | Default value | Description | |
|---|---|---|---|---|---|
| 1 | title |
str |
YES | - | Title to look up |
| 2 | country |
str |
NO | "US" |
Country to search for offers |
| 3 | language |
str |
NO | "en" |
Language of responses |
| 4 | count |
int |
NO | 4 |
Up to how many entries should be returned |
| 5 | best_only |
bool |
NO | True |
Determines whether only best offers should be returned |
country must be ISO 3166-1 alpha-2 2-letter code , e.g. US, GB, FR.
It should be uppercase, however lowercase codes are automatically converted to uppercase.
language is a ISO 639-1 (usually) 2-letter code, lowercase, e.g. en, fr.
count determines up to how many entries should be returned.
If JustWatch GraphQL API returns fewer entries, then this function will also return fewer values.
best_only determines whether similar offers, but lower quality should be included in response.
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.
Returned value is a list of MediaEntry objects.
Example command and its output is in examples/search_output.py.
Details function allows for looking up details for a single entry via its node ID.
Node ID can be taken from output of the search command.
Output from this function contains the same data as a single entry from the search command.
There's no reason to first use the search command, then use node ID from one of entries for this command.
from simplejustwatchapi.justwatch import details
results = details("nodeID", "US", "en", False)Only the first argument is required - the node ID of element to look up details for.
| Argument | Type | Required | Default value | Description | |
|---|---|---|---|---|---|
| 1 | node_id |
str |
YES | - | Node ID to look up |
| 2 | country |
str |
NO | "US" |
Country to search for offers |
| 3 | language |
str |
NO | "en" |
Language of responses |
| 5 | best_only |
bool |
NO | True |
Determines whether only best offers should be returned |
General usage of these arguments matches the search command.
Returned value is a single MediaEntry object.
Example command and its output is in examples/details_output.py.
This function allows looking up offers for entry by given node ID. It allows specifying a set of countries, instead of a single one. This way you can simultaneously look up offers for multiple countries.
from simplejustwatchapi.justwatch import offers_for_countries
results = offers_for_countries("nodeID", {"US", "UK", "CA"}, "en", True)First two arguments are required - node ID, and set of countries.
| Argument | Type | Required | Default value | Description | |
|---|---|---|---|---|---|
| 1 | node_id |
str |
YES | - | Node ID to look up |
| 2 | countries |
set[str] |
YES | - | Set of countries to look up offers for |
| 3 | language |
str |
NO | "en" |
Language of responses |
| 5 | best_only |
bool |
NO | True |
Determines whether only best offers should be returned |
Usage of language and best_only arguments matches the search command.
Returned value dict[str, list[Offer]], where key is country given as argument and value is a list of Offer tuples.
Example command and its output is in examples/offers_for_countries_output.py.
Detailed descriptions of all used data structures are available in the documentation.
Languages and countries are configured via ISO standard. Countries are following ISO 3166-1 alpha-2 standard (2-letter codes, uppercase). Languages are following ISO 639-1 standard (usually 2-letter codes, lowercase).
Language codes can also be country-specific, e.g. es-MX for Mexican Spanish, etc.
The country part must be uppercase.
There is a list of supported locales in JustWatch REST API documentation. Any combination of those languages and countries should work with this API as well.
If you provide unsupported language JustWatch API should default to english.
This API is in no way affiliated, associated, authorized, endorsed by, or in any way officially connected with JustWatch. This is an independent and unofficial project. Use at your own risk.