Simple JustWatch Python API

https://electronic-mango.github.io/simple-justwatch-python-api/
Admin
Simple JustWatch Python API is an unofficial Python library that uses GraphQL to search and retrieve...
Tokens:30,612
Snippets:175
Trust Score:9.7
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install simple-justwatch-python-api with pip, uv, or poetry

Source: https://electronic-mango.github.io/simple-justwatch-python-api/installation

Install the simple-justwatch-python-api package using pip, uv, or poetry. The package is available on PyPi for Python 3.11+.

```bash
pip install simple-justwatch-python-api

```

```bash
uv add simple-justwatch-python-api

```

```bash
poetry add simple-justwatch-python-api

```

--------------------------------

### Get offers for multiple countries for all seasons of a TV show

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Combines search, seasons, and offers_for_countries functions to retrieve offers for each season of a TV show (e.g., Andor) across multiple countries (US and DE). The example builds a dictionary mapping country codes to lists of offers for each season.

```python
from simplejustwatchapi import offers_for_countries, search, seasons

title = "Andor"

# Search for a title.
search_results = search(title)

# Look for a first match with the expected title.
first_match = next(
    result
    for result in search_results
    if result.title == title and result.object_type == "SHOW"
)

# Get all seasons.
all_seasons = seasons(first_match.entry_id)

# Get offers for each season for each country.
countries = {"US", "DE"}
season_offers = [
    offers_for_countries(season.entry_id, countries)
    for season in all_seasons
]

# Convert to a dict of country codes to list of offers.
season_offers_per_country = {
    country: [
        season[country]
        for season in season_offers
    ]
    for country in countries
}

```

--------------------------------

### Example returned dictionary structure for offers_for_countries

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

Shows the structure of the returned dictionary when the countries set from the previous example is used. Keys match the exact case of the input country codes.

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

--------------------------------

### Example countries set for offers_for_countries

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

Example of a set of country codes passed to the countries parameter. The codes are case-insensitive but the returned dictionary keys will match the exact case provided.

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

--------------------------------

### Get offers for each episode of a TV show based on title

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Combines search, seasons, and episodes functions to retrieve offers for each episode of a TV show (e.g., True Detective). The example finds the first matching show, gets all seasons, and builds a nested dictionary mapping season and episode numbers to their offers.

```python
from simplejustwatchapi import episodes, search, seasons

title = "True Detective"

# Search for a title.
search_results = search(title)

# Look for a first match with the expected title.
first_match = next(
    result
    for result in search_results
    if result.title == title and result.object_type == "SHOW"
)

# Get all seasons.
all_seasons = seasons(first_match.entry_id)

# Create a dict with episode offers.
id_to_episodes_offers = {
    season.season_number: {
        episode.episode_number: episode.offers
        for episode in episodes(season.entry_id)
    }
    for season in all_seasons
}

```

--------------------------------

### Source code for offers_for_countries

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

The full source code of the offers_for_countries function as it appears in src/simplejustwatchapi/justwatch.py. It includes the docstring with examples and detailed parameter descriptions.

```python
def offers_for_countries(
    node_id: str,
    countries: set[str],
    language: str = "en",
    best_only: bool = True,
) -> dict[str, list[Offer]]:
    """
    Get offers for entry of given node ID for all given countries.

    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. For example, for countries specified as:
    ```python
    {"uK", "Us", "AU", "ca"}
    ```
    Returned dict will have the following structure:
    ```python
    {
        "uK": [ ... offers ... ],
        "Us": [ ... offers ... ],
        "AU": [ ... offers ... ],
        "ca": [ ... offers ... ],
    }
    ```

    Args:
        node_id (str): ID of entry to look up offers for.

        countries (set[str]): 2-letter country codes for which offers are selected.

            They seem to match **ISO 3166-1 alpha-2** standard (e.g., `EN`, `FR`, `DE`),
            however the API doesn't specify it directly. They should be uppercase,
            however they're normalized to uppercase automatically.

        language (str): Code for language in responses (e.g., description, title).

            It consists of 2 lowercase letters with optional uppercase alphanumeric
            suffix after `-` symbol (e.g., `en`, `en-US`, `de`, `de-CH1901`). Similar to
            **IETF BCP 47** standard, however the suffix can contain only uppercase
            letters and numbers.

            Its value isn't normalized and **must** be provided in expected format,
            including letter case.

        best_only (bool): Return only best offers if `True`, return all offers if
            `False`.

            If service offers the same title in 4K, HD, and SD, then `best_only = True`
            returns only 4K, `best_only = False` returns all three.

    Returns:
        (dict[str, list[Offer]]): Keys match values in `countries` and values are all
            found offers for their respective countries.

    Raises:
        exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
            due to invalid language or country code.
        exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
            responded with non-`2xx` status code.
    """
```

--------------------------------

### Get popular titles using popular function

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Returns a list of currently popular titles. All arguments are optional. Usage and output similar to search without a title. For large searches, use best_only=True or offset for pagination. Output example in examples/popular_output.py.

```python
from simplejustwatchapi import popular

results = popular("US", "en", 5, True, 0, ["nfx", "apv"])

for entry in results:
    print(entry.title, entry.offers)

```

--------------------------------

### Get all seasons of a TV show using seasons function

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Looks up details for all seasons of a TV show based on its node ID. Only the first argument (node ID) is required. Output example in examples/seasons_output.py.

```python
from simplejustwatchapi import seasons

results = seasons("tss20091", "US", "en", True)

for season in results:
    print(season.season_number, season.total_episode_count)

```

--------------------------------

### Get provider codes with providers() and filter popular

Source: https://electronic-mango.github.io/simple-justwatch-python-api/caveats

Use the `providers` function to fetch provider codes for a country (here "GB") and filter by provider name. The resulting list of `short_name` codes (e.g., `nfx`, `amp`) can be passed to `popular` via the `providers` argument to restrict results to those providers.

```python
from simplejustwatchapi import popular, providers

codes = [
    package.short_name
    for package
    # Look up all providers in the UK:
    in providers("GB")
    # Only get codes for specific providers:
    if package.name in ("Netflix", "Amazon Prime Video")
]

# codes == ["nfx", "amp"]

# Get popular titles only for selected providers:
popular_netflix_amazon = popular(providers=codes)

```

--------------------------------

### Get details for a title by node ID using details function

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Looks up details for a single entry via its node ID. Only the first argument (node ID) is required. Node ID can be taken from search output. Works for all media types; some fields are None for certain types. Output example in examples/details_output.py.

```python
from simplejustwatchapi import details

result = details("tm19698", "US", "en", False)

print(result.title, result.short_description)

```

--------------------------------

### Search for a title using search function

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Searches for titles matching a given string. All arguments are optional; the first argument is the title string. If empty or not provided, returns popular titles. For large searches, use best_only=True or offset for pagination. Output example in examples/search_output.py.

```python
from simplejustwatchapi import search

results = search("The Matrix", "US", "en", 5, True, 0, ["nfx", "apv"])

for entry in results:
    print(entry.title, entry.offers)

```

--------------------------------

### Retrieve TV show episode details using simplejustwatchapi.episodes

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

This example calls episodes() with a season node ID, country, language, and a boolean flag, then iterates through the returned Episode list to print episode IDs, numbers, and offers. Only the first argument (season node ID) is required. The JustWatch API returns only a subset of fields for episodes.

```python
from simplejustwatchapi import episodes

results = episodes("tse334769", "US", "en", False)

for episode in results:
    print(episode.episode_id, episode.episode_number, episode.offers)
```

--------------------------------

### Get entries 1990-1999 with count=9 and offset=1990

Source: https://electronic-mango.github.io/simple-justwatch-python-api/caveats

Retrieves entries 1990-1999 (a 9-element list) using count=9 and offset=1990. The API returns up to the 1999th entry; this example stays within that limit.

```python
from simplejustwatchapi import search

results = search("title", count=9, offset=1990)
# len(results) == 9, as expected.

```

--------------------------------

### providers(country: str = 'US') -> list[OfferPackage]

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

Function to look up all providers for a given country.

```APIDOC
## `providers(country: str = 'US') -> list[OfferPackage]`

### Description
Look up all providers for the given country.

### Parameters
- `country` (str) - Optional - 2-letter country code for which offers are selected. It seems to be **ISO 3166-1 alpha-2** standard (e.g., `EN`, `FR`, `DE`), however the API doesn't specify it directly. It should be uppercase, however it's normalized to uppercase automatically. Default: `'US'`.

### Returns
- `list[OfferPackage]` - List of all found providers. `OfferPackage` tuple matches values in `Offer` (and thus in `MediaEntry`), but the data structure is the same, so the same tuple is reused.

### Raises
- `JustWatchApiError` - JSON response from API has internal errors, e.g., due to invalid language or country code.
- `JustWatchHttpError` - HTTP error occurred, e.g., JustWatch API responded with non-`2xx` status code.
```

--------------------------------

### Search for titles with simplejustwatchapi

Source: https://electronic-mango.github.io/simple-justwatch-python-api

Shows how to import the search function and perform a basic search for titles. The search call specifies country, language, and result count, then iterates over the returned entries to print title, object type, and number of offers.

```python
from simplejustwatchapi import search

results = search("The Matrix", country="US", language="en", count=3)

for entry in results:
    print(entry.title, entry.object_type, len(entry.offers))

```

--------------------------------

### search(title: str = '', country: str = 'US', language: str = 'en', count: int = 4, best_only: bool = True, offset: int = 0, providers: list[str] | str | None = None, min_release_year: int | None = None, max_release_year: int | None = None, object_types: list[str] | str | None = None) -> list[MediaEntry]

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

Function to search for media entries with various filters.

```APIDOC
## `search(title: str = '', country: str = 'US', language: str = 'en', count: int = 4, best_only: bool = True, offset: int = 0, providers: list[str] | str | None = None, min_release_year: int | None = None, max_release_year: int | None = None, object_types: list[str] | str | None = None) -> list[MediaEntry]`

### Description
Search for media entries based on the given parameters.
```

--------------------------------

### seasons(show_id: str, country: str = 'US', language: str = 'en', best_only: bool = True) -> list[MediaEntry]

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

Get details of all seasons available for a given show ID. Use the `episodes` function to get details for each episode of a single season.

```APIDOC
## Function: seasons

### Description
Get details of all seasons available for a given show ID. Use the `episodes` function to get details for each episode of a single season.

### Signature
`seasons(show_id: str, country: str = 'US', language: str = 'en', best_only: bool = True) -> list[MediaEntry]`

### Parameters
- **show_id** (str) - Required - ID of a show to look up seasons for.
- **country** (str) - Optional, default: `'US'` - 2-letter country code for which offers are selected. It seems to be **ISO 3166-1 alpha-2** standard (e.g., `EN`, `FR`, `DE`), however the API doesn't specify it directly. It should be uppercase, however it's normalized to uppercase automatically.
- **language** (str) - Optional, default: `'en'` - Code for language in responses (e.g., description, title). It consists of 2 lowercase letters with optional uppercase alphanumeric suffix after `-` symbol (e.g., `en`, `en-US`, `de`, `de-CH1901`). Similar to **IETF BCP 47** standard, however the suffix can contain only uppercase letters and numbers. Its value isn't normalized and **must** be provided in expected format, including letter case.
- **best_only** (bool) - Optional, default: `True` - Return only best offers if `True`, return all offers if `False`. If service offers the same title in 4K, HD, and SD, then `best_only = True` returns only 4K, `best_only = False` returns all three.

### Returns
- **list[MediaEntry]** - List of tuples with seasons data about requested show.

### Raises
- **JustWatchApiError** - JSON response from API has internal errors, e.g., due to invalid language or country code.
- **JustWatchHttpError** - HTTP error occurred, e.g., JustWatch API responded with non-`2xx` status code.

### Source Code
```python
def seasons(
    show_id: str, country: str = "US", language: str = "en", best_only: bool = True
) -> list[MediaEntry]:
    """
    Get details of all seasons available for a given show ID.

    You can use [`episodes`][simplejustwatchapi.justwatch.episodes] function to get
    details for each episode of a single season.

    Args:
        show_id (str): ID of a show to look up seasons for.

        country (str): 2-letter country code for which offers are selected.

            It seems to be **ISO 3166-1 alpha-2** standard (e.g., `EN`, `FR`, `DE`),
            however the API doesn't specify it directly. It should be uppercase, however
            it's normalized to uppercase automatically.

        language (str): Code for language in responses (e.g., description, title).

            It consists of 2 lowercase letters with optional uppercase alphanumeric
            suffix after `-` symbol (e.g., `en`, `en-US`, `de`, `de-CH1901`). Similar to
            **IETF BCP 47** standard, however the suffix can contain only uppercase
            letters and numbers.

            Its value isn't normalized and **must** be provided in expected format,
            including letter case.

        best_only (bool): Return only best offers if `True`, return all offers if
            `False`.

            If service offers the same title in 4K, HD, and SD, then `best_only = True`
            returns only 4K, `best_only = False` returns all three.

    Returns:
        (list[MediaEntry]): List of tuples with seasons data about requested show.

    Raises:
        exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
            due to invalid language or country code.

        exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
            responded with non-`2xx` status code.

    """
    request = prepare_seasons_request(show_id, country, language, best_only)
    response = _post_to_jw_graphql_api(request)
    return parse_seasons_response(response)
```
```

--------------------------------

### offers_for_countries(node_id: str, countries: set[str], language: str = 'en', best_only: bool = True) -> dict[str, list[Offer]]

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

Documentation for the offers_for_countries function, which retrieves offers for a given node ID across multiple countries.

```APIDOC
## offers_for_countries(node_id: str, countries: set[str], language: str = 'en', best_only: bool = True) -> dict[str, list[Offer]]

### Description
Get offers for entry of given node ID for all given countries. 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.

### Parameters
- **node_id** (str) - Required - ID of entry to look up offers for.
- **countries** (set[str]) - Required - 2-letter country codes for which offers are selected. They seem to match **ISO 3166-1 alpha-2** standard (e.g., `EN`, `FR`, `DE`), however the API doesn't specify it directly. They should be uppercase, however they're normalized to uppercase automatically.
- **language** (str) - Optional (default: `'en'`) - Code for language in responses (e.g., description, title). It consists of 2 lowercase letters with optional uppercase alphanumeric suffix after `-` symbol (e.g., `en`, `en-US`, `de`, `de-CH1901`). Similar to **IETF BCP 47** standard, however the suffix can contain only uppercase letters and numbers. Its value isn't normalized and **must** be provided in expected format, including letter case.
- **best_only** (bool) - Optional (default: `True`) - Return only best offers if `True`, return all offers if `False`. If service offers the same title in 4K, HD, and SD, then `best_only = True` returns only 4K, `best_only = False` returns all three.

### Returns
- **dict[str, list[Offer]]** - Keys match values in `countries` and values are all found offers for their respective countries.

### Raises
- **JustWatchApiError** - JSON response from API has internal errors, e.g., due to invalid language or country code.
- **JustWatchHttpError** - HTTP error occurred, e.g., JustWatch API responded with non-`2xx` status code.

### Example
```python
# Example usage
result = offers_for_countries(
    node_id="12345",
    countries={"uK", "Us", "AU", "ca"},
    language="en",
    best_only=True
)
# Result structure:
# {
#     "uK": [ ... offers ... ],
#     "Us": [ ... offers ... ],
#     "AU": [ ... offers ... ],
#     "ca": [ ... offers ... ],
# }
```
```

--------------------------------

### Use numeric strings for int parameters

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

This example shows that numeric strings like '5' can be used for integer arguments such as 'count' because requests are sent as JSON. No exception is raised when using a numeric string.

```python
from simplejustwatchapi import search

results = search("The Matrix", count="5")
# No exception is raised.
```

--------------------------------

### Catch JustWatchApiError for invalid country code

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Use this snippet to catch API errors when the country code matches the 2-letter pattern but is not valid for any country. The example prints all error messages from the 'errors' field.

```python
from simplejustwatchapi import search, JustWatchApiError

try:
    # Country code matches 2-letter pattern, but isn't a valid code for any country.
    results = search("The Matrix", country="xx")
except JustWatchApiError as e:
    # Print all error messages.
    error_messages = [error.get("message") for error in e.errors]
    print(",".join(error_messages))
```

--------------------------------

### Fetch offers for multiple countries using simplejustwatchapi.offers_for_countries

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Calls offers_for_countries() with a title ID, a set of country codes, language, and a boolean flag, then iterates over the returned dictionary to print offers per country. The first two arguments (ID and a set of country codes) are required.

```python
from simplejustwatchapi import offers_for_countries

results = offers_for_countries("tm10", {"US", "UK", "CA"}, "en", True)

for country, offers in results.items():
    print(f"Offers for {country}:")
    for offer in offers:
        print(f"  - {offer.package.name}: {offer.monetization_type}")
```

--------------------------------

### Catch JustWatchError for invalid details ID

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Use this snippet to catch both API and HTTP exceptions with the base JustWatchError class when passing a title instead of an ID to the 'details' function. The example prints the 'errors' attribute.

```python
from simplejustwatchapi import details, JustWatchError

try:
    # "details" expects an ID, not a title.
    results = details("The Matrix")
except JustWatchError as e:
    # JustWatchError will catch both API and HTTP exceptions.
    print(e.errors)
```

--------------------------------

### Extract provider codes from search results and use in popular

Source: https://electronic-mango.github.io/simple-justwatch-python-api/caveats

Extract provider codes from search results by iterating over offers and their packages. Build a dictionary mapping package names to `short_name` codes, then pass the values as a list to `popular` via the `providers` argument. Keep the country code consistent and ensure `providers` is a list, not a dict.

```python
from simplejustwatchapi import popular, search

search_results = search("The Matrix", "US", "en", 5, True)
name_to_code_dict = {
    # Get name and short_name/code from packages:
    offer.package.name: offer.package.short_name
    for entry in search_results  # Iterate all entries.
    for offer in entry.offers  # Iterate all offers per entry.
}
# Keep country code the same between functions, as different countries might have
# different provider codes.
# Also, "providers" needs to be a list, not a dict.
popular_results = popular("US", providers=list(name_to_code_dict.values()))

```

--------------------------------

### Requesting too many entries raises JustWatchApiError

Source: https://electronic-mango.github.io/simple-justwatch-python-api/caveats

This example shows the failure mode when requesting too many entries at once. Calling `popular(count=1980)` raises a `JustWatchApiError` because the operation complexity is too high. Use pagination instead to avoid this error.

```python
from simplejustwatchapi import popular

results = popular(count=1980)
# JustWatchApiError is raised due to too high operation complexity.

```

--------------------------------

### search(title, country, language, count, best_only, offset, providers, min_release_year, max_release_year, object_types)

Source: https://electronic-mango.github.io/simple-justwatch-python-api/API%20Reference/functions

Documentation for the search function in the simple-justwatch-python-api library.

```APIDOC
## search(title, country, language, count, best_only, offset, providers, min_release_year, max_release_year, object_types)

### Description
Search JustWatch for the given title. If no `title` is provided (or an empty string, as per default value) you'll get a selection of "popular" titles. Without `title` the output is very similar to `popular` function.

### Method
Function call

### Parameters
#### Parameters
- **title** (str) - Optional - Title to search. Not stripped, passed to the API as-is. Default: `''`
- **country** (str) - Optional - 2-letter country code for which offers are selected. It seems to be **ISO 3166-1 alpha-2** standard (e.g., `EN`, `FR`, `DE`), however the API doesn't specify it directly. It should be uppercase, however it's normalized to uppercase automatically. Default: `'US'`
- **language** (str) - Optional - Code for language in responses (e.g., description, title). It consists of 2 lowercase letters with optional uppercase alphanumeric suffix after `-` symbol (e.g., `en`, `en-US`, `de`, `de-CH1901`). Similar to **IETF BCP 47** standard, however the suffix can contain only uppercase letters and numbers. Its value isn't normalized and **must** be provided in expected format, including letter case. Default: `'en'`
- **count** (int) - Optional - Return up to this many results. Too high values can cause API errors due to too high operation complexity, if you need more results, use with `offset` argument to get them in batches. Default: `4`
- **best_only** (bool) - Optional - Return only best offers if `True`, return all offers if `False`. If service offers the same title in 4K, HD, and SD, then `best_only = True` returns only 4K, `best_only = False` returns all three. Default: `True`
- **offset** (int) - Optional - Offset for the first returned result, i.e. how many first entries should be skipped. This is done on API side, not the library side; the returned list is still directly parsed from API response. I'm not sure if it guarantees stability of results - if repeated calls to this function with increasing offset will guarantee that you won't get repeats. Default: `0`
- **providers** (list[str] | str | None) - Optional - Selection of 3-letter service identifiers (e.g, `nfx` for "Netflix") to filter for. For single provider you can either pass a single string, or a list of one string. For `None` (the default value) no filtering is done. Invalid codes will be ignored, however if all are invalid, then no filtering is done. You can look up values through `providers` function. Default: `None`
- **min_release_year** (int | None) - Optional - Minimum release year of returned titles. If `None` (the default value), no filtering is done. Default: `None`
- **max_release_year** (int | None) - Optional - Maximum release year of returned titles. If `None` (the default value), no filtering is done. Default: `None`
- **object_types** (list[str] | str | None) - Optional - Types of objects to filter for, like `SHOW` or `MOVIE`. 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 TV shows, same as `SHOW`. While the type value is not enforced, it **must** be a valid type, otherwise API will respond with HTTP status code 422. For single type it can be a single string, or a list with one string. If `None` (the default value), no filtering is done. Default: `None`

### Returns
- **list[MediaEntry]** - List of tuples with details of search results.

### Raises
- **JustWatchApiError** - JSON response from API has internal errors, e.g., due to invalid language or country code.
- **JustWatchHttpError** - HTTP error occurred, e.g., JustWatch API responded with non-`2xx` status code.
```

--------------------------------

### Attempt to get entries 1990-2000 with count=10 and offset=1990

Source: https://electronic-mango.github.io/simple-justwatch-python-api/caveats

Attempts to retrieve entries 1990-2000, but the API returns an empty list because the 2000th entry is not allowed. The library returns an empty list when the request exceeds the maximum number of entries.

```python
from simplejustwatchapi import search

results = search("title", count=10, offset=1990)
# len(results) == 0, API responded with empty list.

```

--------------------------------

### Get popular titles for only specific providers

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Combines the providers and popular functions to filter popular titles by specific providers (e.g., Netflix and Apple TV) in the US. The provider codes are extracted from the provider objects and passed to the popular function.

```python
from simplejustwatchapi import popular, providers

# Get all providers in the US.
all_providers = providers("US")

# Filter only required providers by name.
netflix_apple_only = [
    provider.short_name  # We only need the codes for filtering.
    for provider in all_providers
    if provider.name in ("Netflix", "Apple TV")  # Get providers we need.
]

# Use found codes for filtering.
filtered_popular = popular("US", providers=netflix_apple_only)

```

--------------------------------

### search(title, country, language, count, best_only, offset, providers)

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Searches for media entries by title. Returns a list of MediaEntry objects with title and offers. All arguments are optional; an empty or omitted title returns popular titles.

```APIDOC
## search(title, country, language, count, best_only, offset, providers)

### Description
Searches for media entries based on a title. Returns a list of MediaEntry objects.

### Method
Function call (SDK)

### Endpoint
N/A - Python function

### Parameters
- **title** (string) - Optional - The title to search for. If empty or not provided, returns popular titles.
- **country** (string) - Optional - 2-letter country code, e.g., 'US', 'GB'.
- **language** (string) - Optional - Code for response language, e.g., 'en', 'en-US'.
- **count** (integer) - Optional - How many entries to return.
- **best_only** (boolean) - Optional - If true, returns only best offers per provider.
- **offset** (integer) - Optional - Number of first entries to skip for pagination.
- **providers** (list) - Optional - List of provider short names (e.g., ['nfx', 'apv']).

### Request Example
from simplejustwatchapi import search
results = search("The Matrix", "US", "en", 5, True, 0, ["nfx", "apv"])

### Response
Returns a list of MediaEntry objects, each with `title` and `offers` attributes.

### Notes
- The title is not whitespace-stripped; multiple spaces may return empty results.
- For large searches, use best_only=True or offset for pagination.
```

--------------------------------

### List all available providers using simplejustwatchapi.providers

Source: https://electronic-mango.github.io/simple-justwatch-python-api/usage

Calls providers() with a country code, then filters the returned list of OfferPackage objects by name to get Netflix and Apple TV. This function can be used to obtain provider short_name values (3-letter codes) for the search and popular functions.

```python
from simplejustwatchapi import providers

results = providers("US")

netflix_apple_only = [
    provider
    for provider in all_providers
    if provider.name in ("Netflix", "Apple TV")
]
```
Tokens:
Raw