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)#

Return a list of search results for a query.

Parameters:: query (str) – the search query
Returns:: a list of search results
Return type:: List[Dict[str, str | int]]

TMDB#

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

Note

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, api_key=None, region=None)#

Search for movies on TMDb.

Parameters:

query (str) – the query string
api_key (str | None) – an api_key can either be provided here or through a TMDB_API_KEY env var
region (str | None) – 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”)

Returns:

the search results

Return type:

List[Dict[str, Any]]

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, regions, api_key=None)#

Return a list of streaming providers for a given movie.

Parameters:

tmdb_movie_id (str) – the tmdb id of the movie
regions (List[str]) – a list of regions to trim down the return list
api_key (str | None) – an api_key can either be provided here or through a TMDB_API_KEY env var

Returns:

a dictionary of streaming providers, keyed by region name

Return type:

Dict[str, Any]