pyflix2: python module for accessing Netflix webservice¶
Netflix discontinuting developer program¶
Unfortunately netflix has stopped issuing new developer api keys: https://techcrunch.com/2013/03/08/netflix-stops-issuing-api-keys-to-new-developers-effectively-ending-its-developer-program/ I haven’t tested if the api endpoint are still available or now.
Introduction¶
pyflix2 is a BSD licensed python module for accessing netflix API (both v1 and v2) Netflix provides REST interfaces to access it’s catalog and various user data. This module exposes easy to use object oriented interfaces that is inteded to make it even easier for python programmers to use.
Install¶
Installing requests is simple with pip:
$ pip install pyflix2
or, with easy_install:
$ easy_install pyflix2
Example¶
from pyflix2 import *
netflix = NetflixAPIV2( 'appname', 'key', 'shared_secret')
movies = netflix.title_autocomplete('Terminator', filter='instant')
for title in movies['autocomplete']['title']:
print title
user = netflix.get_user('use_id', 'access_token', 'access_token_secret')
reco = user.get_reccomendations()
for movie in reco['recommendations']:
print movie['title']['regular']
- Note
- Here
appname
,key
andshared_secret
needs to be obtained from: http://developer.netflix.com/apps/mykeys. - The
user_id
,access_token
,access_token_secret
needs to be obtained programmatically usingget_request_token
andget_access_token
- Here
Features¶
- Supports both V1 and V2 of netflix REST API
- Supports both out-of-bound (oauth 1.0a) and vanila three legged oauth auhentication
- Provides easy to use and well documented functional interface for all the API exposed by netflix
- Throws Exception for all kinds of error situation making it easier to integrate with other program
- V1 and V2 APIs are exposed using different classes, so version specific features can be used easily
- Internally uses Requests for making HTTP calls
- Want any new feature? please file a feature request
Documentation: http://pyflix2.readthedocs.org/en/latest/index.html
Note: I would like to thank Kirsten Jones for the library http://code.google.com/p/pyflix/ As pyflix2 was initially inspired by pyflix.
Requirements¶
- Requires
requests
module minimumv1.1.0
- Install latest version of requests-oauthlib:
pip install -U git+git://github.com/requests/requests-oauthlib.git
User Guide¶
All of pyflix2’s functionality can be access via the classes NetflixAPIV1
or NetflixAPIV2
based on
the version you want to use and User
.
Netflix API endpoint to Method Mapping¶
URL | Signature | More |
---|---|---|
/oauth/request_token | get_request_token(use_OOB=True) | get_request_token() |
/catalog/titles | search_titles(term, filter=None, expand=None, start_index=0, max_results=25) | search_titles() |
/catalog/titles/full | get_catalog(**) | get_catalog() |
/catalog/people | search_people(term, start_index=None, max_results=None) | search_people() |
/catalog/titles/movies/title_id, | get_title(id, category=None) | get_title() |
/oauth/access_token | get_access_token(request_token, request_token_secret, oauth_verification_code=None) | get_access_token() |
/catalog/people/person_id | get_person(id) | get_person() |
/users/current | get_user(user_id, user_token, user_token_secret) | get_user() |
/catalog/titles/autocomplete | title_autocomplete(term, filter=None, start_index=None, max_results=None) | title_autocomplete() |
** | get_movie_by_title(movie_title, filter=None) | get_movie_by_title() |
URL | Signature | More |
---|---|---|
/users/user_id/title_states | get_title_states(title_refs=None) | get_title_states() |
/users/userID/recommendations | get_recommendations(start_index=None, max_results=None) | get_recommendations() |
/users/userID/ratings/title/predicted | get_predicted_ratings(title_refs) | get_predicted_ratings() |
/users/userID/queues/instant/saved/entryID | delete_queue_instant_saved(entry_id) | delete_queue_instant_saved() |
/users/userID/ratings/title/actual | get_actual_rating(title_refs) | get_actual_rating() |
/users/userID/ratings/title/actual | add_my_rating(title_ref, rating) | add_my_rating() |
/users/userID/queues | get_queues(expand=None, sort_order=None, start_index=None, max_results=None, updated_min=None) | get_queues() |
/users/userID/ratings/title | get_rating(title_refs) | get_rating() |
/users/user_id | get_details(**) | get_details() |
/users/userID/queues/instant/saved | get_queues_instant_saved(expand=None, entry_id=None, sort_order=None, start_index=None, max_results=None, updated_min=None) | get_queues_instant_saved() |
/users/userID/queues/disc | get_queues_disc(expand=None, sort_order=None, start_index=None, max_results=None, updated_min=None) | get_queues_disc() |
/users/user_id/feed | get_feeds(**) | get_feeds() |
/users/userID/queues/instant/available/entryID | delete_queues_instant_available(entry_id) | delete_queues_instant_available() |
/users/userID/rental_history | get_rental_history(type=None, start_index=None, max_results=None, updated_min=None) | get_rental_history() |
/users/userID/queues/instant | get_queues_instant(expand=None, sort_order=None, start_index=None, max_results=None, updated_min=None) | get_queues_instant() |
/users/userID/ratings/title/actual/ratingID | get_my_rating(rating_id) | get_my_rating() |
** | get_resource(url, data={}) | get_resource() |
/users/userID/ratings/title/actual/ratingID | update_my_rating(rating_id, rating) | update_my_rating() |
/users/userID/queues/instant | add_queue_instant(title_ref, position, etag) | add_queue_instant() |
/users/userID/queues/instant/available | get_queues_instant_available(entry_id=None, sort_order=None, start_index=None, max_results=None, updated_min=None) | get_queues_instant_available() |
API¶
-
pyflix2.
EXPANDS
= [u'@title', u'@box_art', u'@synopsis', u'@short_synopsis', u'@format_availability', u'@screen_formats', u'@cast', u'@directors', u'@languages_and_audio', u'@awards', u'@similars', u'@bonus_materials', u'@seasons', u'@episodes', u'@discs']¶ list() -> new empty list list(iterable) -> new list initialized from iterable’s items
-
pyflix2.
SORT_ORDER
= ['queue_sequence', 'date_added', 'alphabetical']¶ list() -> new empty list list(iterable) -> new list initialized from iterable’s items
-
pyflix2.
RENTAL_HISTORY_TYPE
= ['shipped', 'returned', 'watched']¶ list() -> new empty list list(iterable) -> new list initialized from iterable’s items
-
class
pyflix2.
NetflixAPIV2
(appname, consumer_key, consumer_secret, access_token=None, logger=None)[source]¶ Provides functional interface to Netflix V2 REST api
-
__init__
(appname, consumer_key, consumer_secret, access_token=None, logger=None)[source]¶ The main class for accessing the Netflix REST API v2.0 http://developer.netflix.com/page/Netflix_API_20_Release_Notes It provides all the methods needed to access the resources exposed by netflix. The version 2.0 of the API is backward incompitable. So going forward netflix may deprectate the version 1.0 APIs. So it is recommended to use this class for accessing netflix API.
Parameters: - appname – The Application name as registered in Netflix Developer website <http://developer.netflix.com/apps/mykeys>
- consumer_key – The consumer key as registered in Netlflix Developer website
- consumer_secret – The consumer secret as registerde in Netflix Developer website
- logger – (Optional) The stream object to write log to. Nothing is logged if logger is None
-
search_titles
(term, filter=None, expand=None, start_index=0, max_results=25)[source]¶ Use the catalog titles resource to search the netflix movie catalog(includes all medium) for titles of movies and television series.
url: /catalog/titles
Parameters: - term – The word or term to search the catalog for. The Netflix API searches the title and synopses of catalog titles for a match.
- filter – The filter could be either the string “instant” or “disc”
- expand – The expand parameter instructs the API to expand the
expand
("@title", "@box_art"
, seeEXPANDS
) part of data and include that data inline in the element - start_index – (optional) The zero-based offset into the list that results
from the query. By using this with the
max_results
parameter, user - max_results – (optinoal) The maximum number of results to return. This number cannot be greater than 100. Can request successive pages of search results.
Returns: Returns the matching titles as a series of
catalog_title
records in relevance order, and the total number of results inresults_per_page
.Return type:
-
title_autocomplete
(term, filter=None, start_index=None, max_results=None)[source]¶ Searches the catalog for for movies and television series whose “short” titles match a partial search text. You can then pass the title names that Netflix API returns from this request to the title search methods in order to conduct the actual title search. You can only autocomplete titles (not other items, like names of actors).
url: /catalog/titles/autocomplete
Parameters: - term – The string to look for partial match in short titles
- start_index – (optional) The zero-based offset into the list that results from the query.
- filter – (optional)The filter could be either the string “instant” or “disc”
- max_results – (optinoal) The maximum number of results to return.
Returns: Returns a list of movie and television title names that match your partial search text.
-
get_movie_by_title
(movie_title, filter=None)[source]¶ Returns the first movie that matches the title
Parameters: - movie_title – The exact movie name
- filter – The filter
Returns: the movie object matching the title
-
get_catalog
(catalog_type='full', chunk_size=4096, raw=False)[source]¶ Retrieve a complete index of all instant-watch/dvd titles in the Netflix catalog
Parameters: catalog_type – The type of catalog to fetch; see CATALOG_TYPES_V2
- URLs:
- /catalog/titles/full /catalog/titles/streaming /catalog/titles/dvd
Returns: Returns an iter object which can be written to disk etc
-
get_access_token
(request_token, request_token_secret, oauth_verification_code=None)¶ Obtains the access token/secret, given:
- The
request_token
andrequest_token_secret
has been authorized by visiting the netflix authorization URL by user - The user has obtained the verification code (when
use_OOB
was set inget_request_token
from netflix website)
url: /oauth/access_token
Parameters: - request_token – The request token obtained using :meth: get_request_token
- request_token_secret – The request token secret obtained using
get_request_token()
- oauth_verification_code – (Optional) The verification code obtained from netflix website, if
use_OOB
was set toTrue
inget_request_token()
Returns: Returns the triplet
(user_id, access_token, access_token_secret)
Return type: (string, string, string)
- The
-
get_person
(id)¶ You can retrieve detailed information about a person in the Catalog, using that person’s ID, that includes a biography, featured titles, and a complete list of titles
url: /catalog/people/person_id
Parameters: id – This is the id that is returned for the person in search_people
call (id looks likehttp://api.netflix.com/catalog/people/185930
Returns: The dict object containng details of the person
-
get_request_token
(use_OOB=True)¶ Obtains the request token/secret and the authentication URL
url: /oauth/request_token
Parameters: use_OOB – (Optional) If set to false the oauth out-of-bound authentication is used which requires the user to go to nerflix website and get the verfication code and provide here Returns: Returns the triplet (request_token, request_token_secret , url)
Return type: (string, string, string)
-
get_title
(id, category=None)¶ Retrieve details for specific catalog title
url: /catalog/titles/movies/title_id, /catalog/titles/series/series_id, /catalog/titles/series/series_id/seasons/season_id, /catalog/titles/programs/program_id
Parameters: - id – This is the id that is returned for movies in
search_movie
call (id looks likehttp://api.netflix.com/catalog/titles/movies/60000870
) - category – The expand parameter instructs the API to get (
"title", "box_art"
, seeEXPANDS
without the @ though) information of the movie
Returns: The detail of the movie OR (award/category..) etc of the movie as mentioned by category
- id – This is the id that is returned for movies in
-
get_user
(user_id, user_token, user_token_secret)¶ Returns the user object, which could then be used to make further user specific calls
url: /users/current :param user_id: The user id as received using the
get_access_token()
method :param user_token: The user token as received using theget_access_token()
method :param user_token_secret: The user token secret as received using theget_user_token()
methodReturns: dict
object containg user information. The return object is different for v1 and v2
-
search_people
(term, start_index=None, max_results=None)¶ search for people in the catalog by their name or a portion of their name.
url: /catalog/people
Parameters: - term – The term in the person’s name to search for in the catalog.
- start_index – (optional) The zero-based offset into the list that results from the query.
- max_results – (optinoal) The maximum number of results to return.
Retruns: Returns results that include catalog title entries for titles that involve people that match the specified name. Results also include references to person details.
-
-
class
pyflix2.
NetflixAPIV1
(appname, consumer_key, consumer_secret, logger=None)[source]¶ Provides functional interface to Netflix V1 REST api
-
__init__
(appname, consumer_key, consumer_secret, logger=None)[source]¶ The main class for accessing the Netflix REST API v1.0 http://developer.netflix.com/docs/REST_API_Reference It provides all the methods needed to access the resources exposed by netflix. Netflix has now released version 2.0 http://developer.netflix.com/page/Netflix_API_20_Release_Notes which is backward incompatible. So going forward netflix may deprectate the version 1.0 APIs. So it is recommended to use version 2.0 API instead
Parameters: - appname – The Application name as registered in Netflix Developer website <http://developer.netflix.com/apps/mykeys>
- consumer_key – The consumer key as registered in Netlflix Developer website
- consumer_secret – The consumer secret as registered in Netflix Developer website three legged authentication
- logger – (Optional) The stream object to write log to. Nothing is logged if logger is None
-
search_titles
(term, start_index=0, max_results=25)[source]¶ Use the catalog titles resource to search the netflix movie catalog(includes all medium) for titles of movies and television series.
url: /catalog/titles
Parameters: - term – The word or term to search the catalog for. The Netflix API searches the title and synopses of catalog titles for a match.
- start_index – (optional) The zero-based offset into the list that results from the query. By using this with the max_results parameter, user
- max_results – (optinoal) The maximum number of results to return. This number cannot be greater than 100. If you do not specify max_results, the default value is 25. can request successive pages of search results.
Returns: Returns the matching titles as a series of catalog_title records in relevance order, and the total number of results in results_per_page.
-
title_autocomplete
(term, start_index=None, max_results=None)[source]¶ Searches the catalog for for movies and television series whose “short” titles match a partial search text. You can then pass the title names that Netflix API returns from this request to the title search methods in order to conduct the actual title search. You can only autocomplete titles (not other items, like names of actors).
url: /catalog/titles/autocomplete
Parameters: - term – The string to look for partial match in short titles
- start_index – (optional) The zero-based offset into the list that results from the query.
- max_results – (optinoal) The maximum number of results to return.
Returns: Returns a list of movie and television title names that match your partial search text.
-
get_movie_by_title
(movie_title)[source]¶ Returns the first movie that matches the title
Parameters: movie_title – The exact movie name Returns: the movie object matching the title
-
get_catalog
(catalog_type='index', chunk_size=4096, raw=False)[source]¶ Retrieve a complete index of all instant-watch titles in the Netflix catalog
Parameters: catalog_type – The type of catalog to fetch; see CATALOG_TYPES_V1
- URLs:
- /catalog/titles/index /catalog/titles/streaming /catalog/titles/dvd
Returns: Returns an iter object which can be written to disk etc
-
get_access_token
(request_token, request_token_secret, oauth_verification_code=None)¶ Obtains the access token/secret, given:
- The
request_token
andrequest_token_secret
has been authorized by visiting the netflix authorization URL by user - The user has obtained the verification code (when
use_OOB
was set inget_request_token
from netflix website)
url: /oauth/access_token
Parameters: - request_token – The request token obtained using :meth: get_request_token
- request_token_secret – The request token secret obtained using
get_request_token()
- oauth_verification_code – (Optional) The verification code obtained from netflix website, if
use_OOB
was set toTrue
inget_request_token()
Returns: Returns the triplet
(user_id, access_token, access_token_secret)
Return type: (string, string, string)
- The
-
get_person
(id)¶ You can retrieve detailed information about a person in the Catalog, using that person’s ID, that includes a biography, featured titles, and a complete list of titles
url: /catalog/people/person_id
Parameters: id – This is the id that is returned for the person in search_people
call (id looks likehttp://api.netflix.com/catalog/people/185930
Returns: The dict object containng details of the person
-
get_request_token
(use_OOB=True)¶ Obtains the request token/secret and the authentication URL
url: /oauth/request_token
Parameters: use_OOB – (Optional) If set to false the oauth out-of-bound authentication is used which requires the user to go to nerflix website and get the verfication code and provide here Returns: Returns the triplet (request_token, request_token_secret , url)
Return type: (string, string, string)
-
get_title
(id, category=None)¶ Retrieve details for specific catalog title
url: /catalog/titles/movies/title_id, /catalog/titles/series/series_id, /catalog/titles/series/series_id/seasons/season_id, /catalog/titles/programs/program_id
Parameters: - id – This is the id that is returned for movies in
search_movie
call (id looks likehttp://api.netflix.com/catalog/titles/movies/60000870
) - category – The expand parameter instructs the API to get (
"title", "box_art"
, seeEXPANDS
without the @ though) information of the movie
Returns: The detail of the movie OR (award/category..) etc of the movie as mentioned by category
- id – This is the id that is returned for movies in
-
get_user
(user_id, user_token, user_token_secret)¶ Returns the user object, which could then be used to make further user specific calls
url: /users/current :param user_id: The user id as received using the
get_access_token()
method :param user_token: The user token as received using theget_access_token()
method :param user_token_secret: The user token secret as received using theget_user_token()
methodReturns: dict
object containg user information. The return object is different for v1 and v2
-
search_people
(term, start_index=None, max_results=None)¶ search for people in the catalog by their name or a portion of their name.
url: /catalog/people
Parameters: - term – The term in the person’s name to search for in the catalog.
- start_index – (optional) The zero-based offset into the list that results from the query.
- max_results – (optinoal) The maximum number of results to return.
Retruns: Returns results that include catalog title entries for titles that involve people that match the specified name. Results also include references to person details.
-
-
class
pyflix2.
User
(netflix_client, user_id, access_token, access_token_secret)[source]¶ -
__init__
(netflix_client, user_id, access_token, access_token_secret)[source]¶ Don’t use this constructor directly, use
get_user()
insteadParameters: - netflix_client – The Netflix client
- access_token – (Optional) User access token obtained using OAuth three legged authentication
- access_token_secret – (Optional) User access token secret obtained using OAuth three legged authentication
-
get_details
()[source]¶ Returns information about the subscriber with the specified user ID url: /users/user_id
-
get_feeds
()[source]¶ Netflix API returns a list of URLs of all feeds available for the specified user. url: /users/user_id/feed
-
get_title_states
(title_refs=None)[source]¶ returns a series of records that indicate the relationship between the subscriber and one or more titles. url: /users/user_id/title_states
Parameters: title_refs – list of catalog title URLs Returns: relationship between the subscriber and the movies he has added to qeueu
-
get_queues
(expand=None, sort_order=None, start_index=None, max_results=None, updated_min=None)[source]¶ Returns the contents of a subscriber’s queue. url: /users/userID/queues
Parameters: - sort_order – One of queue_sequence, date_added or alphabetical. Default is queue_sequence
- start_index – The zero-based offset into the results for the query
- max_results – Maximum number of results you want.
- updated_min – Only results whose updated time is greater than this would be returned. Unix epoch time format or RFC 3339 format
Returns: Subscriber’s queue
-
get_queues_instant
(expand=None, sort_order=None, start_index=None, max_results=None, updated_min=None)[source]¶ Returns details about a subscriber’s instant watch queue
url: /users/userID/queues/instant
Parameters: - sort_order – One of queue_sequence, date_added or alphabetical. Default is queue_sequence
- start_index – The zero-based offset into the results for the query
- max_results – Maximum number of results you want.
- updated_min – Only results whose updated time is greater than this would be returned. Unix epoch time format or RFC 3339 format
Returns: Subscriber’s instant-watch queue
-
get_queues_disc
(expand=None, sort_order=None, start_index=None, max_results=None, updated_min=None)[source]¶ Returns details about a subscriber’s disc queue url: /users/userID/queues/disc
Parameters: - sort_order – One of queue_sequence, date_added or alphabetical. Default is queue_sequence
- start_index – The zero-based offset into the results for the query
- max_results – Maximum number of results you want.
- updated_min – Only results whose updated time is greater than this would be returned. Unix epoch time format or RFC 3339 format
Returns: Subscriber’s disc queue
-
add_queue_instant
(title_ref, position, etag)[source]¶ These resources automatically add the title to the saved or available queue, depending on the title’s availability. Use
get_title_states()
to see the status of the movie in your queueurl: /users/userID/queues/instant
Parameters: - title_ref – The catalog title to be added to the queue.
- position – The position (positions start with “1”) in the queue at which to insert or move the title.
- etag – The queue’s ETag value that Netflix API returned the last time you accessed the queue. Use this for concurrency control.
Returns: If it is successful, Netflix API returns the queue entries that got created or modified with your POST request. If this request involved moving a title within a queue, the API returns only that queue item with its updated position. The API throws an error if a title is not available. The POST operation fails if the queue has been updated since the time you retrieved the ETag value that you passed in. Each successful (or partially successful) POST response includes a new ETag value that you can then use in subsequent requests.
-
get_queues_instant_available
(entry_id=None, sort_order=None, start_index=None, max_results=None, updated_min=None)[source]¶ Retrieves availability details about the subscriber’s instant-watch queue
url: /users/userID/queues/instant/available
Parameters: - sort_order – One of queue_sequence, date_added or alphabetical. Default is queue_sequence
- start_index – The zero-based offset into the results for the query
- max_results – Maximum number of results you want.
- updated_min – Only results whose updated time is greater than this would be returned. Unix epoch time format or RFC 3339 format
Returns: Subscriber’s availability details of instant-watch queue
-
delete_queues_instant_available
(entry_id)[source]¶ deletes the specified entry from the subscriber’s instant watch queue. url: /users/userID/queues/instant/available/entryID
Parameters: entry_id – the entry id
-
get_queues_instant_saved
(expand=None, entry_id=None, sort_order=None, start_index=None, max_results=None, updated_min=None)[source]¶ Returns the saved status of an entry in a subscriber’s instant-watch queue. url: /users/userID/queues/instant/saved
Parameters: - sort_order – One of queue_sequence, date_added or alphabetical. Default is queue_sequence
- start_index – The zero-based offset into the results for the query
- max_results – Maximum number of results you want.
- updated_min – Only results whose updated time is greater than this would be returned. Unix epoch time format or RFC 3339 format
-
delete_queue_instant_saved
(entry_id)[source]¶ Deletes the specified entry from the subscriber’s instant-watch queue. url: /users/userID/queues/instant/saved/entryID
Parameters: entry_id – The entry_id
-
get_rental_history
(type=None, start_index=None, max_results=None, updated_min=None)[source]¶ - Get a list of titles that reflect a subscriber’s viewing history
- Note: This API to be obsolete on 15th Sept, 2012 http://goo.gl/AYOlt
url: /users/userID/rental_history
Parameters: - type – type of rental history, “watched”, “shipped” etc, see
RENTAL_HISTORY_TYPE
- start_index – The zero-based offset into the results for the query
- max_results – Maximum number of results you want.
- updated_min – Only results whose updated time is greater than this would be returned. Unix epoch time format or RFC 3339 format
-
get_rating
(title_refs)[source]¶ Returns a list of movie or television series ratings for the designated subscriber. If available, the subscriber’s actual ratings are returned; otherwise, the resource returns the Netflix-predicted ratings. url: /users/userID/ratings/title
Parameters: title_refs – List of title ids Returns: List of rating of given titles
-
get_actual_rating
(title_refs)[source]¶ Get rating for titles given by the subscriber url: /users/userID/ratings/title/actual
Parameters: title_refs – List of title ids
-
add_my_rating
(title_ref, rating)[source]¶ Add user’s custom rating url: /users/userID/ratings/title/actual
Parameters: - title_ref – List of title ids
- rating – the rating
-
get_my_rating
(rating_id)[source]¶ Get particular rating that uesr has already given using the rating id url: /users/userID/ratings/title/actual/ratingID
Parameters: rating_id – the integer rating id
-
update_my_rating
(rating_id, rating)[source]¶ Udate particular rating that uesr has already given using the rating id url: /users/userID/ratings/title/actual/ratingID
Parameters: - rating_id – the integer rating id
- rating – the rating
-
get_predicted_ratings
(title_refs)[source]¶ Get predicted rating for given titles url: /users/userID/ratings/title/predicted
Parameters: title_refs – List of title ids
-
get_recommendations
(start_index=None, max_results=None)[source]¶ Get Netflix’s catalog title recommendations for a subscriber, based on a subscriber’s viewing history. url: /users/userID/recommendations
Parameters: - start_index – The zero-based offset into the results for the query
- max_results – Maximum number of results you want.
-