pyflix2: python module for accessing Netflix webservice

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('access_token', 'access_token_secret')
reco = user.get_reccomendations()
for movie in reco['recommendations']:
    print movie['title']['regular']
Note
  • Here appname, key and shared_secret needs to be obtained from: http://developer.netflix.com/apps/mykeys.
  • The access_token, access_token_secret needs to be obtained programmatically using get_request_token and get_access_token

Commandline

$ python -mpyflix2 -s 'the matrix' -x

Or see help:

$ python -mpyflix2 -h

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.

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

NetflixAPIV2 api
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/index 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_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()
User api
URL Signature More
/users/user_id/title_states get_title_states(title_refs=None) get_title_states()
/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/recommendations get_reccomendations(start_index=None, max_results=None) get_reccomendations()
/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 = ['@title', '@box_art', '@synopsis', '@short_synopsis', '@format_availability', '@screen_formats', '@cast', '@directors', '@languages_and_audio', '@awards', '@similars', '@bonus_materials', '@seasons', '@episodes', '@discs']

Allowed expand strings while calling the titles api

pyflix2.SORT_ORDER = ['queue_sequence', 'date_added', 'alphabetical']

Allowed sort order while retrieveing queues

pyflix2.RENTAL_HISTORY_TYPE = ['shipped', 'returned', 'watched']

Allowed type to use while calling get_rental_history()

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", see EXPANDS) 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 in results_per_page.

Return type:

dict

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_access_token(request_token, request_token_secret, oauth_verification_code=None)

Obtains the access token/secret, given:

  • The request_token and request_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 in get_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 to True in get_request_token()
Returns :

Returns the pair (access_token, access_token_secret)

Return type:

(string, string)

get_catalog()

Retrieve a complete index of all instant-watch titles in the Netflix catalog

url: /catalog/titles/index

Returns :Returns an iter object which can be written to disk etc
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 like http://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 like http://api.netflix.com/catalog/titles/movies/60000870)
  • category – The expand parameter instructs the API to get ("title", "box_art", see EXPANDS without the @ though) information of the movie
Returns:

The detail of the movie OR (award/category..) etc of the movie as mentioned by category

get_user(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_token: The user token as received using the get_access_token() method :param user_token_secret: The user token secret as received using the get_user_token() method

Returns: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_access_token(request_token, request_token_secret, oauth_verification_code=None)

Obtains the access token/secret, given:

  • The request_token and request_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 in get_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 to True in get_request_token()
Returns :

Returns the pair (access_token, access_token_secret)

Return type:

(string, string)

get_catalog()

Retrieve a complete index of all instant-watch titles in the Netflix catalog

url: /catalog/titles/index

Returns :Returns an iter object which can be written to disk etc
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 like http://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 like http://api.netflix.com/catalog/titles/movies/60000870)
  • category – The expand parameter instructs the API to get ("title", "box_art", see EXPANDS without the @ though) information of the movie
Returns:

The detail of the movie OR (award/category..) etc of the movie as mentioned by category

get_user(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_token: The user token as received using the get_access_token() method :param user_token_secret: The user token secret as received using the get_user_token() method

Returns: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, access_token, access_token_secret, id=None)[source]
__init__(netflix_client, access_token, access_token_secret, id=None)[source]

Don’t use this constructor directly, use get_user() instead

Parameters:
  • 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
  • id – The user id of the netflix subsriber
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 queue

url: /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_resource(url, data={})[source]
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_reccomendations(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.

exception pyflix2.NetflixError[source]

Error thrown if the netflix api throws http error

pyflix2 is a BSD licensed python module for accessing netflix API

Links

Table Of Contents

This Page

Fork me on GitHub