Skip to content

Tools

phylm also offers some tools and utilities related to movies.

Search movies

For a given movie title query you can return a list of search results from IMDb through search_movies:

>>> from phylm.tools import search_movies
>>> search_movies("the matrix")
[{
  'title': 'The Matrix',
  'kind': 'movie',
  'year': 1999,
  'cover_photo': 'https://some-url.com',
  'imdb_id': '0133093',
}, {
  'title': 'The Matrix Reloaded',
  'kind': 'movie',
  'year': 2003,
  'cover_photo': 'https://some-url.com',
  'imdb_id': '0234215',
}, {
...

phylm.tools.search_movies(query: str) -> List[Dict[str, Union[str, int]]]

Return a list of search results for a query.

Parameters:

Name Type Description Default
query str

the search query

 required

Returns:

Type Description
List[Dict[str, Union[str, int]]]

a list of search results

TMDB

phylm also provides tools to interact with The Movie Database (TMDb).

To use TMDb tools you'll need to sign up for an API key, instructions here. Once you have your key, export it as an env var called TMDB_API_KEY so that it's available to use in these tools. You also have the option of passing in the key as an argument to each function.

Search movies

For a given movie title query you can return a list of search results from TMDb through search_tmdb_movies. Note that this search performs a lot quicker than the imdb search_movies.

>>> from phylm.tools import search_tmdb_movies
>>> search_tmdb_movies("The Matrix", api_key="abc") # the api key can be provided as an env var instead
[{
  'adult': False,
  'backdrop_path': '/fNG7i7RqMErkcqhohV2a6cV1Ehy.jpg',
  'genre_ids': [28, 878],
  'id': 603,
  'original_language': 'en',
  'original_title': 'The Matrix',
  'overview': 'Set in the 22nd century, The Matrix tells the story of a computer hacker...'
  'popularity': 79.956,
  'poster_path': '/f89U3ADr1oiB1s9GkdPOEpXUk5H.jpg',
  'release_date': '1999-03-30',
  'title': 'The Matrix',
  'video': False,
  'vote_average': 8.2,
  'vote_count': 20216,
}, {
  ...
}

By default the release_date will be the US release date. You can specify a different region by providing a region argument:

>>> from phylm.tools import search_tmdb_movies
>>> search_tmdb_movies("The Matrix", region="gb")
[{
  'id': 603,
  ...
  'release_date': '1999-06-11',
  'title': 'The Matrix',
  ...
}, {
  ...
}

phylm.tools.search_tmdb_movies(query: str, api_key: Optional[str] = None, region: Optional[str] = None) -> List[Dict[str, Any]]

Search for movies on TMDb.

Parameters:

Name Type Description Default
query str

the query string

 required
api_key Optional[str]

an api_key can either be provided here or through a TMDB_API_KEY env var

 None
region Optional[str]

an optional region to provide with the search request, affects the release_date value returned, must be provided in ISO 3166-1 format (eg. "us" or "gb")

 None

Returns:

Type Description
List[Dict[str, Any]]

List[Dict[str, Any]]: the search results

Get streaming providers

For a given movie TMDb id and list of regions, you can return a list of streaming providers from TMDb via Just Watch through get_streaming_providers.

>>> from phylm.tools import get_streaming_providers
>>> get_streaming_providers(tmdb_movie_id="438631", regions=["gb"], api_key="abc")
{
  'gb': {
    'link': 'https://www.themoviedb.org/movie/438631-dune/watch?locale=GB',
    'rent': [{
      'display_priority': 8,
      'logo_path': '/pZgeSWpfvD59x6sY6stT5c6uc2h.jpg',
      'provider_id': 130,
      'provider_name': 'Sky Store',
    }],
  },
}

Consult the TMDb docs for more information on the data that's returned.

phylm.tools.get_streaming_providers(tmdb_movie_id: str, regions: List[str], api_key: Optional[str] = None) -> Dict[str, Any]

Return a list of streaming providers for a given movie.

Parameters:

Name Type Description Default
tmdb_movie_id str

the tmdb id of the movie

 required
regions List[str]

a list of regions to trim down the return list

 required
api_key Optional[str]

an api_key can either be provided here or through a TMDB_API_KEY env var

 None

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: a dictionary of streaming providers, keyed by region name
Last update: 2023-10-18