simplejustwatchapi package

Submodules

simplejustwatchapi.justwatch module

Main module orchestrating requests to JustWatch GraphQL API.

simplejustwatchapi.justwatch.details(node_id: str, country: str = 'US', language: str = 'en', best_only: bool = True) → MediaEntry[source]

Get details of entry for a given ID.

best_only allows filtering out redundant offers, e.g. when if provide offers service in 4K, HD and SD, using best_only = True returns only 4K option, best_only = False returns all three.

Parameters:

  • node_id – ID of entry to look up

  • country – country to search for offers, US by default

  • language – language of responses, en by default

  • best_only – return only best offers if True, return all offers if False

Returns:

MediaEntry NamedTuple with data about requested entry.

simplejustwatchapi.justwatch.offers_for_countries(node_id: str, countries: set[str], language: str = 'en', best_only: bool = True) → dict[str, list[Offer]][source]

Get offers for entry of given node ID for all countries passed as argument. Language argument only specifies format of price string, e.g. whether “.”, or “,” is used in decimal fractions.

Returned dict has keys matching countries argument and values are list of found offers. If no countries are passed (an empty set given as argument) empty dict is returned.

Country codes passed as argument are case-insensitive, however keys in returned dict will match them exactly. E.g. for countries specified as:

{"uK", "Us", "AU", "ca"}

returned dict will have the following structure:

{
    "uK": [ ... offers ... ],
    "Us": [ ... offers ... ],
    "AU": [ ... offers ... ],
    "ca": [ ... offers ... ],
}

best_only allows filtering out redundant offers, e.g. when if provide offers service in 4K, HD and SD, using best_only = True returns only 4K option, best_only = False returns all three.

Parameters:

  • node_id – ID of entry to look up offers for

  • countries – set of country codes to search for offers

  • language – language of responses, en by default

  • best_only – return only best offers if True, return all offers if False

Returns:

dict where keys match values in countries and keys are all found offers for their respective countries

simplejustwatchapi.justwatch.search(title: str, country: str = 'US', language: str = 'en', count: int = 4, best_only: bool = True) → list[MediaEntry][source]

Search JustWatch for given title.

Returns a list of entries up to count.

best_only allows filtering out redundant offers, e.g. when if provide offers service in 4K, HD and SD, using best_only = True returns only 4K option, best_only = False returns all three.

Parameters:

  • title – title to search

  • country – country to search for offers, US by default

  • language – language of responses, en by default

  • count – how many responses should be returned

  • best_only – return only best offers if True, return all offers if False

Returns:

List of MediaEntry NamedTuples parsed from JustWatch response

simplejustwatchapi.query module

Module responsible for creating GraphQL queries and parsing responses from JustWatch GraphQL API. Parsed responses are returned as Python NamedTuples for easier access.

class simplejustwatchapi.query.Interactions(likes: int | None, dislikes: int | None)[source]

Bases: NamedTuple

Parsed data regarding number of likes and dislikes on JustWatch for a single entry.

dislikes: int | None

Number of dislikes on JustWatch.

likes: int | None

Number of likes on JustWatch.

class simplejustwatchapi.query.MediaEntry(entry_id: str, object_id: int, object_type: str, title: str, url: str, release_year: int, release_date: str, runtime_minutes: int, short_description: str, genres: list[str], imdb_id: str | None, tmdb_id: str | None, poster: str | None, backdrops: list[str], age_certification: str | None, scoring: Scoring | None, interactions: Interactions | None, streaming_charts: StreamingCharts | None, offers: list[Offer])[source]

Bases: NamedTuple

Parsed response from JustWatch GraphQL API for “GetSearchTitles” query for single entry.

age_certification: str | None

“R”, “TV-14”.

Type:

Age rating as a string, e.g.

backdrops: list[str]

List of URLs for backdrops (full screen images to use as background).

entry_id: str

Entry ID, contains type code and numeric ID.

genres: list[str]

List of genre codes for this entry, e.g. ["rly"], ["cmy", "drm", "rma"].

imdb_id: str | None

ID of this entry in IMDB.

interactions: Interactions | None

Interactions (likes/dislikes) data.

object_id: int

Object ID, the numeric part of full entry ID.

object_type: str

Type of entry, e.g. MOVIE, SHOW.

offers: list[Offer]

List of available offers for this entry, empty if there are no available offers.

poster: str | None

URL to poster for this ID.

release_date: str

Full release date as a string, e.g. 2013-12-16.

release_year: int

Release year as a number.

runtime_minutes: int

Runtime in minutes.

scoring: Scoring | None

Scoring data.

short_description: str

Short description of this entry.

streaming_charts: StreamingCharts | None

JustWatch charts/ranks data.

title: str

Full title.

tmdb_id: str | None

ID of this entry in TMDB.

url: str

URL to JustWatch with details for this entry.

class simplejustwatchapi.query.Offer(id: str, monetization_type: str, presentation_type: str, price_string: str | None, price_value: float | None, price_currency: str, last_change_retail_price_value: float | None, type: str, package: OfferPackage, url: str, element_count: int | None, available_to: str | None, deeplink_roku: str | None, subtitle_languages: list[str], video_technology: list[str], audio_technology: list[str], audio_languages: list[str])[source]

Bases: NamedTuple

Parsed single offer from JustWatch GraphQL API for single entry. One platform can have multiple offers for one entry available, e.g. renting, buying, etc.

audio_languages: list[str]

List of 2-letter language codes of available audio tracks, e.g. ["en", "pt", "de"].

audio_technology: list[str]

List of known audio technologies available in this offer, e.g. DOLBY_ATMOS.

available_to: str | None

Date until which this offer will be available.

Deeplink to this offer in Roku.

element_count: int | None

Element count, usually 0.

id: str

Offer ID.

last_change_retail_price_value: float | None

Previous available price if change in price was recorded.

monetization_type: str

Type of monetization of this offer, e.g. FLATRATE (streaming), RENT, BUY.

package: OfferPackage

Information about platform on which this offer is available.

presentation_type: str

Quality of media in this offer, e.g. HD, SD, 4K.

price_currency: str

Represents only currency, without price, or value.

price_string: str | None

Current price as a string with currency, suitable for displaying to users. Format can change based on used language argument.

price_value: float | None

Current price as a numeric value.

subtitle_languages: list[str]

List of 2-letter language codes of available subtitles, e.g. ["en", "pt", "de"].

type: str

Type of offer.

url: str

URL to this offer.

video_technology: list[str]

List of known video technologies available in this offer, e.g. DOLBY_VISION.

class simplejustwatchapi.query.OfferPackage(id: str, package_id: int, name: str, technical_name: str, icon: str)[source]

Bases: NamedTuple

Parsed single offer package from JustWatch GraphQL API for single entry. Contains information about platform on which given offer is available.

icon: str

Platform icon URL.

id: str

ID, defines whole platform on which this offer is available, not a single offer.

name: str

Name of the platform in format suited to display for users.

package_id: int

Package ID, defines whole platform on which this offer is available, not a single offer.

technical_name: str

Technical name of the platform, usually all lowercase with no whitespaces.

class simplejustwatchapi.query.Scoring(imdb_score: float | None, imdb_votes: int | None, tmdb_popularity: float | None, tmdb_score: float | None, tomatometer: int | None, certified_fresh: bool | None, jw_rating: float | None)[source]

Bases: NamedTuple

Parsed data related to user scoring for a single entry.

certified_fresh: bool | None

Flag whether entry has “Certified Fresh” seal on Rotten Tomatoes.

imdb_score: float | None

IMDB score.

imdb_votes: int | None

Number of votes on IMDB.

jw_rating: float | None

JustWatch rating.

tmdb_popularity: float | None

TMDB popularity score.

tmdb_score: float | None

TMDB score.

tomatometer: int | None

Tomatometer score on Rotten Tomatoes.

class simplejustwatchapi.query.StreamingCharts(rank: int, trend: str, trend_difference: int, top_rank: int, days_in_top_3: int, days_in_top_10: int, days_in_top_100: int, days_in_top_1000: int, updated: str)[source]

Bases: NamedTuple

Parsed data related to JustWatch rank for a single entry.

days_in_top_10: int

Number of days in top 10 ranks.

days_in_top_100: int

Number of days in top 100 ranks.

days_in_top_1000: int

Number of days in top 1000 ranks.

days_in_top_3: int

Number of days in top 3 ranks.

rank: int

Rank on JustWatch.

top_rank: int

Top rank ever reached.

trend: str

Trend in ranking on JustWatch, UP, DOWN, STABLE.

trend_difference: int

Difference in rank; related to trend.

updated: str

2024-10-06T09:20:36.397Z.

Type:

Date when rank data was last updated as a string, e.g.

simplejustwatchapi.query.parse_details_response(json: any) → MediaEntry | None[source]

Parse response from details query from JustWatch GraphQL API. Parses response for GetTitleNode query.

If API responded with an internal error (mostly due to not found node ID), then None will be returned instead.

Meant to be used together with prepare_details_request().

Parameters:

json – JSON returned by JustWatch GraphQL API

Returns:

Parsed received JSON as a MediaEntry NamedTuple, or None in case data for a given node ID was not found

simplejustwatchapi.query.parse_offers_for_countries_response(json: any, countries: set[str]) → dict[str, list[Offer]][source]

Parse response from offers query from JustWatch GraphQL API. Parses response for GetTitleOffers query.

Response if searched for country codes passed as countries argument. Countries in JSON response which are not present in countries set will be ignored. If response doesn’t have offers for a country, then that country still will be present in returned dict, just with an empty list as value.

Meant to be used together with prepare_offers_for_countries_request().

Parameters:

  • json – JSON returned by JustWatch GraphQL API

  • countries – set of countries to look for in API response

Returns:

A dict, where keys are matching countries argument and values are offers for a given country parsed from JSON response.

simplejustwatchapi.query.parse_search_response(json: dict) → list[MediaEntry][source]

Parse response from search query from JustWatch GraphQL API. Parses response for GetSearchTitles query.

If API didn’t return any data, then an empty list is returned.

Meant to be used together with prepare_search_request().

Parameters:

json – JSON returned by JustWatch GraphQL API

Returns:

Parsed received JSON as a list of MediaEntry NamedTuples

simplejustwatchapi.query.prepare_details_request(node_id: str, country: str, language: str, best_only: bool) → dict[source]

Prepare a details request for specified node ID to JustWatch GraphQL API. Creates a GetTitleNode GraphQL query.

Country code should be two uppercase letters, however it will be auto-converted to uppercase.

Meant to be used together with parse_details_response().

Parameters:

  • node_id – node ID of entry to get details for

  • country – country to search for offers

  • language – language of responses

  • best_only – return only best offers if True, return all offers if False

Returns:

JSON/dict with GraphQL POST body

simplejustwatchapi.query.prepare_offers_for_countries_request(node_id: str, countries: set[str], language: str, best_only: bool) → dict[source]

Prepare an offers request for specified node ID and for all specified countries to JustWatch GraphQL API. Creates a GetTitleOffers GraphQL query.

Country codes should be two uppercase letters, however they will be auto-converted to uppercase. countries argument mustn’t be empty.

Meant to be used together with parse_offers_for_countries_response().

Parameters:

  • node_id – node ID of entry to get details for

  • countries – list of country codes to search for offers

  • language – language of responses

  • best_only – return only best offers if True, return all offers if False

Returns:

JSON/dict with GraphQL POST body

simplejustwatchapi.query.prepare_search_request(title: str, country: str, language: str, count: int, best_only: bool) → dict[source]

Prepare search request for JustWatch GraphQL API. Creates a GetSearchTitles GraphQL query.

Country code should be two uppercase letters, however it will be auto-converted to uppercase.

Meant to be used together with parse_search_response().

Parameters:

  • title – title to search

  • country – country to search for offers

  • language – language of responses

  • count – how many responses should be returned

  • best_only – return only best offers if True, return all offers if False

Returns:

JSON/dict with GraphQL POST body

Module contents