{"id":13824955,"url":"https://github.com/Electronic-Mango/simple-justwatch-python-api","last_synced_at":"2025-07-08T20:32:33.787Z","repository":{"id":209072449,"uuid":"723181769","full_name":"Electronic-Mango/simple-justwatch-python-api","owner":"Electronic-Mango","description":"A simple (and unofficial) JustWatch Python API.","archived":false,"fork":false,"pushed_at":"2024-10-06T14:09:25.000Z","size":2950,"stargazers_count":48,"open_issues_count":8,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-12T04:19:29.953Z","etag":null,"topics":["api","api-graphql","graphql","justwatch","justwatch-api","justwatch-graphql","python","python3"],"latest_commit_sha":null,"homepage":"https://electronic-mango.github.io/simple-justwatch-python-api/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Electronic-Mango.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-24T21:46:06.000Z","updated_at":"2025-06-10T06:13:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"6aad45db-e6dd-462c-aecb-c21d6f54be2a","html_url":"https://github.com/Electronic-Mango/simple-justwatch-python-api","commit_stats":null,"previous_names":["electronic-mango/simple-justwatch-python-api"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/Electronic-Mango/simple-justwatch-python-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Electronic-Mango%2Fsimple-justwatch-python-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Electronic-Mango%2Fsimple-justwatch-python-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Electronic-Mango%2Fsimple-justwatch-python-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Electronic-Mango%2Fsimple-justwatch-python-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Electronic-Mango","download_url":"https://codeload.github.com/Electronic-Mango/simple-justwatch-python-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Electronic-Mango%2Fsimple-justwatch-python-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264343771,"owners_count":23593788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-graphql","graphql","justwatch","justwatch-api","justwatch-graphql","python","python3"],"created_at":"2024-08-04T09:01:12.594Z","updated_at":"2025-07-08T20:32:33.324Z","avatar_url":"https://github.com/Electronic-Mango.png","language":"Python","readme":"# Simple JustWatch Python API\n\n[![CodeQL](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/codeql-analysis.yml)\n[![Black](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/black.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/black.yml)\n[![Flake8](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/flake8.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/flake8.yml)\n[![isort](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/isort.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/isort.yml)\n[![Pytest](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/pytest.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/pytest.yml)\n[![Coverage Status](https://coveralls.io/repos/github/Electronic-Mango/simple-justwatch-python-api/badge.svg?branch=main)](https://coveralls.io/github/Electronic-Mango/simple-justwatch-python-api?branch=main)\n[![PyPI - Version](https://img.shields.io/pypi/v/simple-justwatch-python-api)](https://pypi.org/project/simple-justwatch-python-api/)\n\nA simple unofficial JustWatch Python API which uses [`GraphQL`](https://graphql.org/) to access JustWatch data, built with [`httpx`](https://www.python-httpx.org/) and `Python3.11`.\n\n\n\n## Table of contents\n\n* [Installation](#installation)\n* [Usage](#usage)\n  * [Search](#search)\n  * [Details](#details)\n  * [Offers for countries](#offers-for-countries)\n* [Return data structures](#return-data-structures)\n* [Locale, language, country](#locale-language-country)\n* [Disclaimer](#disclaimer)\n\n\n## Installation\n\nProject is available in [PyPi](https://pypi.org/project/simple-justwatch-python-api/):\n```bash\npip install simple-justwatch-python-api\n```\n\n\n\n## Usage\n\nThis Python API has 3 functions:\n\n - `search` - search for entries based on title\n - `details` - get details for entry based on its node ID\n - `offers_for_countries` - get offers for entry based on its node ID, can look for offers\n   in multiple countries\n\nDetailed documentation is available in https://electronic-mango.github.io/simple-justwatch-python-api/.\n\nExample outputs from all commands are in [`examples/`](examples/) directory.\n\n\n### Search\nSearch functions allows for searching entries based on a given title.\n\n```python\nfrom simplejustwatchapi.justwatch import search\n\nresults = search(\"title\", \"US\", \"en\", 5, True)\n```\n\nOnly the first argument is required, it specifies a title to search.\n\n|   | Argument    | Type   | Required | Default value | Description                                            |\n|---|-------------|--------|----------|---------------|--------------------------------------------------------|\n| 1 | `title`     | `str`  | **YES**  | -             | Title to look up                                       |\n| 2 | `country`   | `str`  | NO       | `\"US\"`        | Country to search for offers                           |\n| 3 | `language`  | `str`  | NO       | `\"en\"`        | Language of responses                                  |\n| 4 | `count`     | `int`  | NO       | `4`           | Up to how many entries should be returned              |\n| 5 | `best_only` | `bool` | NO       | `True`        | Determines whether only best offers should be returned |\n\n`country` must be **ISO 3166-1 alpha-2** 2-letter code , e.g. `US`, `GB`, `FR`.\nIt should be uppercase, however lowercase codes are automatically converted to uppercase.\n\n`language` is a **ISO 639-1** (usually) 2-letter code, lowercase, e.g. `en`, `fr`.\n\n`count` determines **up to** how many entries should be returned.\nIf JustWatch GraphQL API returns fewer entries, then this function will also return fewer values.\n\n`best_only` determines whether similar offers, but lower quality should be included in response.\nIf 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.\n\nReturned value is a list of [`MediaEntry`](#return-data-structures) objects.\n\nExample command and its output is in [`examples/search_output.py`](examples/search_output.py).\n\n\n### Details\n\nDetails function allows for looking up details for a single entry via its node ID.\nNode ID can be taken from output of the [`search`](#search) command.\n\nOutput from this function contains the same data as a single entry from the [`search`](#search) command.\nThere's no reason to first use the [`search`](#search) command, then use node ID from one of entries for this command.\n\n```python\nfrom simplejustwatchapi.justwatch import details\n\nresults = details(\"nodeID\", \"US\", \"en\", False)\n```\n\nOnly the first argument is required - the node ID of element to look up details for.\n\n|   | Argument    | Type   | Required | Default value | Description                                            |\n|---|-------------|--------|----------|---------------|--------------------------------------------------------|\n| 1 | `node_id`   | `str`  | **YES**  | -             | Node ID to look up                                     |\n| 2 | `country`   | `str`  | NO       | `\"US\"`        | Country to search for offers                           |\n| 3 | `language`  | `str`  | NO       | `\"en\"`        | Language of responses                                  |\n| 5 | `best_only` | `bool` | NO       | `True`        | Determines whether only best offers should be returned |\n\nGeneral usage of these arguments matches the [`search`](#search) command.\n\nReturned value is a single [`MediaEntry`](#return-data-structures) object.\n\nExample command and its output is in [`examples/details_output.py`](examples/details_output.py).\n\n\n### Offers for countries\n\nThis function allows looking up offers for entry by given node ID.\nIt allows specifying a set of countries, instead of a single one.\nThis way you can simultaneously look up offers for multiple countries.\n\n```python\nfrom simplejustwatchapi.justwatch import offers_for_countries\n\nresults = offers_for_countries(\"nodeID\", {\"US\", \"UK\", \"CA\"}, \"en\", True)\n```\n\nFirst two arguments are required - node ID, and set of countries.\n\n|   | Argument    | Type       | Required | Default value | Description                                            |\n|---|-------------|------------|:---------|---------------|--------------------------------------------------------|\n| 1 | `node_id`   | `str`      | **YES**  | -             | Node ID to look up                                     |\n| 2 | `countries` | `set[str]` | **YES**  | -             | Set of countries to look up offers for                 |\n| 3 | `language`  | `str`      | NO       | `\"en\"`        | Language of responses                                  |\n| 5 | `best_only` | `bool`     | NO       | `True`        | Determines whether only best offers should be returned |\n\nUsage of `language` and `best_only` arguments matches the [`search`](#search) command.\n\nReturned value `dict[str, list[Offer]]`, where key is country given as argument and value is a list of [`Offer`](#return-data-structures) tuples.\n\nExample command and its output is in [`examples/offers_for_countries_output.py`](examples/offers_for_countries_output.py).\n\n\n\n## Return data structures\n\nDetailed 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).\n\n\n\n## Locale, language, country\n\nLanguages and countries are configured via ISO standard.\nCountries are following **ISO 3166-1 alpha-2** standard (2-letter codes, uppercase).\nLanguages are following **ISO 639-1** standard (usually 2-letter codes, lowercase).\n\nLanguage codes can also be country-specific, e.g. `es-MX` for Mexican Spanish, etc.\nThe country part **must** be uppercase.\n\nThere is a list of supported locales in [JustWatch **REST API** documentation](https://apis.justwatch.com/docs/api/#tips).\nAny combination of those languages and countries should work with this API as well.\n\nIf you provide unsupported language JustWatch API should default to english.\n\n\n\n## Disclaimer\n\nThis API is in no way affiliated, associated, authorized, endorsed by, or in any way officially connected with JustWatch.\nThis is an independent and unofficial project.\nUse at your own risk.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FElectronic-Mango%2Fsimple-justwatch-python-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FElectronic-Mango%2Fsimple-justwatch-python-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FElectronic-Mango%2Fsimple-justwatch-python-api/lists"}