JavaScript API Reference

The Netflix Javascript API allows subscribers to add, save, or instantly watch movies from pages on your web site. You include this API on a page with a single line of JavaScript. To try it out, sign up as a Netflix developer, find your consumer key (sometimes called the "API key" or just your "key") in My Keys, and place the <script> element shown in the examples below in your page at the place where you want the add, save, or watch buttons to show up.

Running the Examples on This Page

To run an example on this page, copy it, paste it into a text editor, substitute your own consumer key for my_consumer_key, save it with an .html extension, and load it into a Web browser.

Netflix Button Sets

<html><head><title>My Spiffy Movie Page</title></head><body>
<div id="myMovieLocation">
<img src="http://cdn-7.nflximg.com/us/boxshots/large/70068647.jpg" /><br />
<script src="http://jsapi.netflix.com/us/api/js/api.js">
{
"title_id" : "http://api.netflix.com/catalog/movie/70068647",
"button_type" : ["PLAY_BUTTON", "ADD_BUTTON"],
"show_logo" : "true",
"x" : "40",
"y" : "20",
"dom_id" : "myMovieLocation",
"application_id" : "my_consumer_key"
}
</script>
</div>
</body></html>

When you load this into your browser, you ought to see a page with box art and a button set for The King of Kong (which we happen to know is usually available for instant watching). If you click the Add button, or mouse over Play and then click the Add to Instant button, the result of this interaction will come up in an <iframe> that is absolutely positioned 40 pixels from the left edge and 20 pixels from the top of the <div> whose id is "myMovieLocation". If you click the Play button, the instant movie viewer will come up in its own browser window.

There's a JSON object inside the <script> tag that consists of key-value pairs inside a set of curly brackets. That's how you pass your parameters to the Netflix JavaScript API, and it must be in the form of a valid JSON object.

Buttons

  • Valid buttons include ADD_BUTTON, SAVE_BUTTON, and PLAY_BUTTON. Put these in the button_type array.
  • Add supersedes Save, so if you try to show them both, you will only see Add. You should only use Save when you are positive that the movie is not available from Netflix yet.
  • If you include a Play button, you will also automatically get the Add to Instant button, which will only show when you mouse over Play.

The Netflix Logo

Although we like to set show_logo to true to make our code easier to explain and maintain, it's not strictly necessary because the logo is on by default. To eliminate it, set show_logo to false.

Title Availability

If you're writing your pages by hand, the fastest way to find out whether a title is available is to go to its page and check for yourself. You can also determine instant-watch availability with the Netflix REST API. Calls like this one:

http://api.netflix.com/catalog/titles/movies/your_movie_id/format_availability

…will tell you if your title is available for instant-watch streaming. For more information on how to make Netflix REST API requests, please consult Common REST API Tasks and the REST API Reference.

Buttonless Calls

If you don't want to use our buttons, you can use your own mechanism to call the addToQueue( ) and openPlayer( ) functions after you include the base API script anywhere in your site.

Watch Instantly

<html><head><title>My Spiffy Movie Page</title></head><body>
<a href="#" onclick="javascript:nflx.openPlayer('http://api.netflix.com/catalog/movie/70068647', 0, 0, 'my_consumer_key');">Watch The King of Kong Now</a>
<script src="http://jsapi.netflix.com/us/api/js/api.js"></script>
</body></html>

Load that code in your browser and you ought to see a page with a single link that will open the Netflix player to play The King of Kong.

Add to Queue

<html><head><title>My Spiffy Movie Page</title></head><body>
<a id="addMe" href="#" onclick="javascript:nflx.addToQueue('http://api.netflix.com/catalog/movie/70068647', 10, 20, 'my_consumer_key', 'disc', 'addMe');">Add The King of Kong to DVD Queue</a>
<script src="http://jsapi.netflix.com/us/api/js/api.js"></script>
</body></html>

Load that code in your browser and you ought to see a page with a single link that will add The King of Kong to your "Watch Later" queue. If you want to add this movie to the subscriber's instant-watch queue, the way the Add to Instant button does, use instant instead of disc as the fifth parameter to addToQueue( ).

Important Notes and Technical Details about Buttonless Actions:

When performing buttonless actions, you directly call JavaScript functions that expect certain parameters to appear in a certain order. Here's how they work:

nflx.addToQueue : function (movieId, xPos, yPos, applicationId, type, domId)
addToQueue( ) expects the movie ID, the X and Y position in pixels from the top of the viewport, your application ID, the queue type you want to add to, and the DOM id of the element you want your X and Y position to be counted from. Only the DOM id is optional.
nflx.openPlayer : function(movieId, xPos, yPos, applicationId, domId)
openPlayer( ) expects the movie ID, the X and Y position in pixels from the top of the viewport, your application ID, and the DOM id you want your X and Y position to be counted from. Only the DOM ID is optional.

Other Useful Things to Know

  • If the Netflix subscriber who views your page is not signed in to Netflix, an authentication window will come up instead of the add, save, or instant-watcher window.
  • Visitors who are not currently Netflix subscribers will be prompted to sign up.
  • If you participate in our affiliate program, you will be awarded a bounty for all new subscribers who sign up from your page. To activate this, send a request to apisupport@netflix.com and include both your Consumer Key and your Affiliate ID in the body of the email.

version 25 as of 8 months ago by David Gross

14 Comments

  1. M Horstmeier – 2 years ago

    I see that the Javascript API supports the consumer token. Is there support for the OAuth access token so I can manage the authentication?

  2. JR Conlin – 2 years ago

    This version of the Javascript API is mostly about using widgets. If you're interested in accessing the full API via Javascript, we'll be officially releasing the Javascript API with version 2.0. You may also wish to look over resources such as OAuthSimple on the Resources page for handling OAuth calls via JSONp.

    Be aware, however, that when you start dealing with Javascript and OAuth, you need to be sure to secure your secrets. Javascript normally doesn't provide that, meaning that anyone could view that information directly.

  3. Saurabh dixit – 2 years ago

    how can we have complete catelogue..

  4. Saurabh dixit – 2 years ago

    how can we add the page which searches for the movie in our web application...because after that we will redirect user over here so that he can have a look in to the movie and watch..please assist me ..I am working on the php...thus I prefer java script api to do so...

    thanks

  5. JR Conlin – 2 years ago

    You can fetch the catalog via the Catalog Title Index call: http://developer.netflix.com/docs/REST_API_Reference#0_42335

    This will return a very large file, however, so I'd recommend doing some server side storage.

    You can read up about how to do title searches using either Autocomplete or the catalog search at http://developer.netflix.com/docs/REST_API_Reference#0_52696 (conveniently located above the catalog/index call).

    I'd also strongly suggest reading about php's libCurl implementation <http://php.net/manual/en/book.curl.php > and SimpleXML <http://php.net/manual/en/book.simplexml.php > (although the catalog index may be too large for simplexml to chew through.

    Currently, JSON support is not officially supported, but will be part of the next public release.

  6. Saurabh dixit – 2 years ago

    I have tried the link
    http://api.netflix.com/catalog/titles?title=ironman&oauth_consumer_key=My Key

    But result Comes
    <h1>400 Bad Request</h1>

  7. Saurabh dixit – 2 years ago

    Thanks for the reply Actually I am new in it..thats why.

    in the rest api pages
    I am having sample response but ..how to make request for that I have tried the above link but not getting any data

  8. Saurabh dixit – 2 years ago

    Actually I want to have same interface ..from which user can search the movies and after getting the availability he can watch trailors or the movie whatever ..

    something like that..

    I have tried to retrieve the complete catalogue by

    http://api.netflix.com/catalog/titles?title=ironman&oauth_consumer_key=My Key

    but out put comes

    <h1>400 Bad Request</h1>

    dont know why??

    on REST api refrence pages I have got response samples so that I can understand it...but ho to call the page/..

    and I have my key ...I have seen there that they need signature also how can I find that..

    Help MEEEE

  9. JR Conlin – 2 years ago

    You need to do more than just add your consumer key.

    Please consult the OAuth walkthrough at: http://developer.netflix.com/walkthrough for what is required.

    As for providing instant watch capability, that is not available via the API.

  10. Fandango Developer – 2 years ago

    We download the full catalog and load it into our database (i.e. 128,000 titles). I am using these javascript api's on our own buttons. I do notice that you have two different types of formats DVD and Blu-ray. When a user clicks add to queue and you have one or the other but the user only wants one (e.g. user has a DVD player and only wants Blu-ray but Blu-ray is the only format), how is that handled? Does a message come up in the iFrame indicating to the user that you only have Blu-ray and no DVD to add to queue?

  11. Mrjava0 – 1 year ago

    How You use REST and Java Script With IMDB www.imdn.com?

  12. DJ – 1 year ago

    nflx:addToQueue pops up a window that is rather large (roughly 250 x 450 pixels). Unfortunately this is much too large on a mobile device (even one with a pretty big screen like an Android G2).

    There doesn't appear to be an easy way to modify api.js to produce a smaller window. Are there any plans to extend the nflx:addToQueue interface so the caller can suggest a size for the window (or maybe just request a smaller fixed size version)? Thanks.

  13. mwforlife1337 – 3 months ago

    How do I add a Netflix logo/button, so when you press it it takes you directly to the movie the button was under?

  14. JM Vazquez – 2 months ago

    Is there a way to have the instant watch player load in the same window from which it was called?

Please sign in to post a comment.