Skip to content
Python 3 API -
Branch: master
Clone or download
Latest commit 0adeb6e Sep 29, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
justwatch add person_id as valid keyword for search Sep 29, 2019
.travis.yml removed python 3.7 in travis conf due to errors curl-ing it Dec 3, 2018
LICENSE Create LICENSE Aug 6, 2017 Add disclaimer to README Jul 16, 2019
api_payload.txt resolve #11, options to retrieve cinema details Jun 2, 2018
requirements.txt remove babel May 12, 2019 Update May 12, 2019

Unofficial JustWatch API

Build Status Python 3 API


python3 -m pip install JustWatch


This is not the official JustWatch API. JustWatch doesn't offer an open API and doesn't plan to do this in the future.

The work of many developers went and is still going into the development and maintenance of the data and the API. JustWatch's main business is to operate a streaming guide with apps for iOS and Android. They offer the data for business intelligence and marketing. Therefore it is prohibited to use the API for commercial use (consumer service, data science, business intelligence, etc.). It is ok to use the API for private projects, but please be respectful with your API calls to not put too much load on the API. The API is not supported in any way and will change frequently without warning.

If you would like to work with JustWatch and use the data/API please get in contact with them via Currently, JustWatch can only work with bigger partners and clients. JustWatch is also hiring: and has some interesting open source projects:

How To

search for an item

from justwatch import JustWatch

just_watch = JustWatch(country='US')

results = just_watch.search_for_item(query='the matrix')

or search for combination of genres

just_watch = JustWatch(genres=['act', 'scf', 'hrr'])

results_by_genres = just_watch.search_for_item()

or maybe search by provider

just_watch = JustWatch()

results_by_providers = just_watch.search_for_item(providers=['nfx', 'stn'])

or possibly a combination of the above

just_watch = JustWatch()

results_by_multiple = just_watch.search_for_item(
    providers=['nfx', 'stn'], 

get list of genres and codes

just_watch = JustWatch(country='GB')
genre_details = just_watch.get_genres()

get list of providers for a country

just_watch = JustWatch(country='DE')
provider_details = just_watch.get_providers()

get further details on a movie or tv program

Based on title id found in previous search

just_watch = JustWatch(country='GB')
megamind = just_watch.get_title(title_id=103561)
dark = just_watch.get_title(title_id=55668, content_type='show')

You can query for title IDs

just_watch = JustWatch(country='GB')
the_matrix = just_watch.get_title_id(query='the matrix')

{'The Matrix': 10, 'The Matrix Revisited': 30701, ...}

get further defails on a specific season of a tv program

season_id can be found in the response from get_title of a tv program

just_watch = JustWatch(country='GB')
hannibal_season2 = just_watch.get_season(season_id=20236)

get country specific certification details

just_watch = JustWatch(country='GB')
certs = just_watch.get_certifications()

content_type can be specified but (for GB at least) setting to 'show' gives less detail than the default of 'movie'

get cinema details

Setting "monetization_types" to "cinema" and possibly setting nationwide_cinema_releases_only = True will return a list of potential showings.

just_watch = JustWatch(country='GB')
cinema_showings = just_watch.search_for_item(monetization_types='cinema')

Then based on title_id obtained from that search

cinema_times = just_watch.get_cinema_times(title_id=this_title_id,

This will return details of all the showings in the area. Details of all the cinemas in the area can be obtained by a call to get_cinema_details(). This takes the same latitutde, longitude and radius parameters as get_cinema_times(), and if a call has already been made they'll be reused.

local_cinemas = just_watch.get_cinema_details()

You can then join the data from the two calls by joining 'cinema_id' from get_cinema_times() with 'id' from get_cinema_details()

get upcoming cinema details

Call get_upcoming_cinema() with number of weeks forward or back and whether you only require national releases

showings_last_week = just_watch.get_upcoming_cinema(weeks_offset=-1, nationwide_cinema_releases_only=True)
showings_three_weeks = just_watch.get_upcoming_cinema(weeks_offset=3, nationwide_cinema_releases_only=False)
Note: Default country is AU

Read api_payload.txt for more information


Contributions are welcome!

Please write unit tests for any new functionality :)

You can’t perform that action at this time.