Sunday, October 2, 2011

Probably bad timing but here is the netflix API I promised.

Well I finally finished the netflix api I promised. Sorry for the delay it just took time to get motivated to finish it. Since I waited it probably doesn't have near the interest that it might have, had netflix not made the silly choices they did.

Anyway without further ado here is the netflix api.

Here is the github repo for it.

As with the other APIs you need to have a developer key for your application so head over to the netflix development docs to register an account and get an API key and secret. Put those values into a config so that they can be included when you initialize the library. Next download the api files and put them in your application directory.

Once they are in place you need to authenticate the API with a netflix account. We do this using OAuth. Checkout the included example controller for how to implement your request and access methods.

Use the oauth access token and token secret to make authenticated requests to the api. This token is a long lived token so you should only need to generate one per netflix user.

Now you can use every method in the library, but I have to warn you the Netflix API responses are XML and are complex. It is by far the most difficult API to work with as many of the requests require data from other requests in order to function properly. We will start with some of the most basic.

$this->netflix->search_title('Jurassic Park');

This command will do a search on the specified title which in this case is the amazing movie "Jurassic Park". No further parameters are needed but the returned data isn't all that useful.

Next we will look at the command to get data on the currently authenticated user.


This command is very important as it will return the ID netflix provides for each user. This ID can be used in future API calls for tasks like managing the users queue. Using this ID we can now make a call to:

$this->netflix->get_queues($id, $type);

This will return all of the titles in the users queue. Use the $type parameter to specify if you want the instant queue or the disc queue. One thing to really keep track of when you are working with a users queue is the returned etag. This is a value that is returned in the XML response that is used to maintain concurrency when managing the queue. Every call to a queue management function will have an etag in the response.

Say you want to add a title to your queue.

$this->netflix->add_queue_entry($id, 'disc', '', $etag);

This will add the title Jurassic Park to your disc queue provided to specified the correct $id for the user and the correct $etag value. There is an optional 5th parameter that lets you specify the position in the queue of the movie.

Now I know what you are thinking: 'Where the crap does he get Jurassic Park from that URL?' Well you have to get that data from another request like search_title. Like I said Netflix doesn't make it easy to use their API.

That is just a taste of what this library can do, it isn't the easiest API to work with unfortunately but it is functional and you can get around in it if you know what you are doing. Now because of that I highly recommend reading the Netflix API documentation you can find it here. It outlines all of the methods this library uses as well as all of the additional parameters you can specify for each call.

Here is a list of all of the currently available methods in the library.

$this->netflix->search_title($title, array $params = array());
$this->netflix->all_titles(array $params = array());
$this->netflix->get_title_details($id, $type, $season = false);
$this->netflix->get_title_similars($id, $type, $season = false, array $params = array());
$this->netflix->search_people($name, array $params = array());
$this->netflix->get_user($id = 'current');
$this->netflix->get_user_feeds($id, array $params = array());
$this->netflix->get_user_title_states($id, array $params = array());
$this->netflix->get_queues($id, $type = '', array $params = array());
$this->netflix->get_queue_state($id, $type, $state, $entry = '', array $params = array());
$this->netflix->remove_queue_entry($id, $type, $state, $entry);
$this->netflix->add_queue_entry($id, $type, $title_ref, $etag, $position = '1');
$this->netflix->get_rental_history($id, $instant_watched = false, array $params = array());
$this->netflix->get_title_rating($id, $title_refs, $predicted = false);
$this->netflix->set_title_rating($id, $title_ref, $rating, $ratingId = false);
$this->netflix->get_recommendations($id, array $params = array());

As always if you have any questions just leave a comment and I will do my best to help you out.


  1. Jim,

    Just want to say thank you for posting this! We have one Netflix account in our family, and when I saw that our children receive suggestions based upon what my wife and I watch and can access our viewing history, I nearly cancelled on the spot. But I knew there had to be a way I could code my own user interface using the API. Thanks to your help, I'm well on the way.

    Mike E.

    1. Glad to hear it. Let me know if you have any issues.

  2. Hi Jim,

    Thanks for ci netflix api. I have a few questions..

    installing / coding
    1) I copied the files to associated folders.
    2) updated the $params['key'] and $params['secret'] in the example file
    3) update site_url("../ci/index.php/example/access_netflix")
    4) created a new function index in the controler/example.php file (I don't think is right way to do)

    public function index() {
    echo "starting" . "
    echo "oauth_token: ". $this->session->userdata('oauth_token'). "
    echo "oauth_token_secret: ". $this->session->userdata('oauth_token_secret'). "
    echo $this->netflix_auth();
    echo "ending" . "

    1st I goto -->
    and do the link account button and echoed out oauth_token and oauth_token_secret
    works fine. (Can i just redirect the user to a new page after this at the end of the access_netflix() function ??)

    2nd I open new tab and goto -->
    but the user is not displayed when executing "netflix_auth();"

    Is this the right approach?

    Question: Does the user have to link account each time or Should I save the "oauth_token and oauth_token_secret" into the database so i can use for same user on new browser session ?

    Can you provide another example what to do after request_netflix, how to get user and perhaps "$this->netflix->get_queues($id, $type);"


    1. Hi Sachin,

      It looks like you might be new to CodeIgniter. I recommend getting a little more familiar with it before using this library.

      Here are a few things I noticed from your code sample:

      1) If you just copied the example controller I provided then you shouldn't need to change any of the site_url calls. Those will automatically point to the right place provided you have properly configured CodeIgniter.

      2) There is no need for an index function in the example controller. Read the CodeIgniter documentation on how controller functions get mapped to URIs. So after you go to: then get returned back you can then go to:

      I hope that clears some things up with your implementation.

      To answer your questions. Yes you should redirect some place at the end of the access_netflix method. In your access_method you should store the oauth_token and oauth_secret in your database then your users will only ever have to authenticate once.

  3. Clearly this is exactly what I refer to a gorgeous blog article! Do you utilize this site for your private purposes exclusively or you actually have it as a source of income?