Netflix API Developer Blog

RSS Feed

Public API Update

Starting today, we will no longer provide expiration dates for any of our titles in the public API.  We will continue to publish the field to the REST API and the catalog index file to minimize the likelihood of breaking applications that use it, although all titles will now have "1/1/2100" as the date value.

We are making this change because the expiration date can be inaccurate as a result of frequent, often last minute, changes in content flow.

Netflix members will still be able to see the listed title expirations on Netflix.com on each individual title page.

- Daniel Jacobson

Changes to the Public API Program

The API program has shifted over the past few years to support our growing and evolving streaming business. Its primary focus is to support the myriad devices used by our 33 million members to stream TV shows and movies from Netflix.  Because of this evolution, we are making additional changes to the public API program.

The changes, outlined below, are designed to allow us to focus our API efforts on supporting the products and features used most by our members. They are also designed to allow us to continue to offer the public API program in a way that aligns with our goals.

The following are the changes we are making to the program, all of which are effective immediately (except where otherwise noted):

  • We will no longer issue new public API developer keys.  All existing keys that are actively calling the API will remain active.
  • We will no longer accept new API affiliates.  There will be no impact to existing and active affiliates.
  • We will no longer offer test environments.  The test tools have been unavailable for a while and we won’t bring them back.
  • We will set the forums in the developer portal to read-only.  We encourage developers to continue their conversations at StackOverflow with the tag “netflixapi”.  The existing forum posts will remain on the site for now in the form of an archive.
  • We will retire the OData catalog, effective on April 8, 2013. 

If you have any questions, please email publicapi@netflix.com.

Daniel Jacobson

Director of Engineering – Netflix API

Update: Changes for the Public API

As a reminder to my previous blog post about the public API changes, all current endpoints for the catalog index files will be shut down as of September 15, 2012, but they will be available until then as developers work to migrate to the new files.  In their place will be two new files:

http://api-public.netflix.com/catalog/titles/streaming

http://api-public.netflix.com/catalog/titles/dvd

To be clear, these two files will support the catalogs for streaming and DVD respectively.  These files are available now.  Over the next few weeks/months, you may notice some DVD elements/attributes in the streaming file and you may notice some streaming elements in the DVD file.  Over time, those straggling features will be fleshed out to leave each file streamlined towards its targeted goal.

Although it may not have been explicitly stated in the past, as the old catalog index files get retired, we will also be removing the files that contain the references to the AMG and TMS IDs, referenced in our documentation.  If your app uses the catalog index files that support those IDs, you will no longer be able to access those IDs as of September 15, 2012.

Daniel Jacobson

Director of Engineering - API

Upcoming Changes to the Netflix API Program

Over the past years the Netflix business has evolved to focus on delivering a great streaming experience on a wide variety of consumer electronics devices. Similarly, we have been evolving our API program to focus on servicing the rapidly growing universe of these devices used by our more than 26 million streaming members globally. As the API program evolves with the business, we now need to make some changes. While we will continue to support third parties as they develop and offer Web sites and applications that interact with Netflix, these changes are designed to do so in a way that is aligned with our broader objectives.

Here is a detailed description of the changes and the timing for each.

Functional Changes

  • We have already modified the value of the <available_until> element for all titles to be 1/1/2100 unless the title is to become unavailable within two weeks of the requesting date.
  • We will be removing the following endpoints, effective on September 15, 2012:
    • /users/userID/rental_history
    • /users/userID/rental_history/shipped
    • /users/userID/rental_history/returned
    • /users/userID/rental_history/watched
    • /users/userID/at_home
  • We will be removing the following elements from the title_states endpoint, effective on September 15, 2012
    • <watched_date>
    • <playback_bookmark>
    • <watched_to_end>
  • We will be removing the following RSS feeds, effective on September 15, 2012:
    • Most Recent Rental Activity
    • Movies At Home
  • We will be removing all metadata for the rental history, recently watched, at home, etc. in all expands for all endpoints.
  • We will be changing the API base URL domain from api.netflix.com to api-public.netflix.com.  This new domain is active now.  All requests will need to point to it by September 15, 2012, when the api.netflix.com domain will be retired.
  • We will be retiring all existing versions of the catalog index files, to be replaced with new catalog index files.  The new files will be structurally the same as the 2.0 version but there will be two files, one for streaming and one for DVD.  The new files will be available in the coming weeks (we will post here with the new endpoints) and we plan to retire all other existing endpoints on September 15, 2012. 
  • We will be retiring the AppGallery pages found at http://www.netflix.com/AppGallery.  This is effective immediately. These pages were outdated and seldom used as people tend to go to various App stores and other Web sites to find applications.

To be clear, none of these changes will affect the Queue-related resources or data.

 Terms of Use Changes

The Terms of Use has been updated and will be effective today.  That said, for developers that have applications that need to be changed, they will be grandfathered in until September 15, 2012.  To view the revised Terms of Use, go to <a href=”http://developer.netflix.com/page/Api_terms_of_use”>http://developer.netflix.com/page/Api_terms_of_use</a>.

Support

From now on, we ask that you now contact Netflix API Support at publicapi@netflix.com as we will be retiring apisupport@netflix.com.  This change is effective immediately. 

If you have questions about these changes, please address them to this new email address or bring them up on the forums. 

- Daniel Jacobson, Director of Engineering for the Netflix API

Netflix Public API Will Continue to Support DVD

Several months ago, we announced that we will be retiring the DVD-related features from the public API.  This was done in anticipation of changes to our DVD business.  However, there will be no changes to our DVD business, so we will now continue DVD support in the public API.  This decision is effective immediately as we have not yet taken any action to remove these features.  

Daniel Jacobson

Director of Engineering - Netflix API

Upcoming Changes to the Open API Program

As of Oct. 14th, 2011, the Netflix API will be focused exclusively on offering content and functionality from the streaming catalog. As a result, we will be discontinuing the support of DVD-related features in the Open API. These changes are in an effort to better position the Netflix API towards the company’s long-term goal of internationalizing our streaming experience. Focusing the API towards streaming will better enable the company to create rich experiences in these new markets. Additionally, over time, we plan to open up the API to become international as well.

The rest of this post includes the list of changes that will take effect in October. Our goal is to make the transition as smooth as possible by gracefully degrading as many of these deprecated features as possible.

The following resources will have DVD-related content removed from them, but they will still work correctly with streaming content only:

  • users/user_ID/title_states
  • users/user_ID/feeds
  • catalog/titles
  • catalog/titles/autocomplete
  • catalog/titles/title/similar
  • catalog/people/person_ID/filmography

The following disc endpoints (on the left of the table) will continue to be valid endpoints but will return a comparable, streaming-oriented result set (the results provided by the right side of the table) until June 1st, 2012, at which time these endpoints will be removed:

Current Endpoint New Endpoint Results
/users/user_ID/queues/disc /users/user_ID/queues/instant
/users/user_ID/queues/disc/available /users/user_ID/queues/instant/available
/users/user_ID/queues/disc/available/entry_ID /users/user_ID/queues/instant/available/entry_ID
/users/user_ID/queues/disc/saved /users/user_ID/queues/instant/saved
/users/user_ID/queues/disc/saved/entry_ID /users/user_ID/queues/instant/saved/entry_ID

The following resources will be deprecated and will return 404 responses:

  • users/user_ID/at_home
  • users/user_ID/rental_history/shipped
  • users/user_ID/rental_history/returned
  • catalog/titles/discs/disc_ID

All category resources will be deprecated. The category scheme attribute will remain, but will no longer resolve. The affected resources include:

  • /categories/title_formats
  • /categories/award_types
  • /categories/screen_formats
  • /categories/rental_states
  • /categories/title_video_formats
  • /categories/languages
  • /categories/subtitle_languages
  • /categories/audio
  • /categories/genres
  • /categories/title_formats
  • /categories/queue_availability
  • /categories/title_states
  • /categories/mpaa_ratings
  • /categories/tv_ratings
  • /categories/ca_movie_ratings
  • /categories/container_formats
  • /categories/video_formats
  • /categories/audio_formats

All resources that return DVD-specific elements will continue to work, although the DVD-specific elements will no longer be returned. This will primarily affect the elements in the catalog/titles/title resource, which will no longer return DVD-related values in the title_formats category.

Currently, there are several endpoints for the catalog index across the versions of the API. Over time, we plan to collapse them into a single index. For this announcement, we plan to leave the current versions the same, although the number of titles will dramatically decrease. The title count will decrease because the index today has both streaming and DVD titles. From this change, it will only contain titles that are available in streaming. We will have future announcements the catalog index in the future as we attempt to globalize it and clean up the endpoints.

The JavaScript Widgets will continue to work, although the will be modified to only work for streaming titles. Titles will no longer be able to be added to the DVD queue through these widgets.

The documentation in the portal is currently being revised to reflect all of these changes. We hope to have it published to the site sometime next week.

During this transition, we will continue to work with our developer community to make the change as smooth as possible.

Daniel Jacobson, Director of Engineering – Netflix API

Changes to genres and playback_bookmark

Genres Are Being Replaced as of June 15

Titles in the Netflix title catalog currently have genres associated with them. For instance, if you request the <catalog_title> record for the animated musical movie Sita Sings the Blues (GET catalog/titles/movies/70113539?v=2.0), the response contains the following genre information:

<?xml version="1.0" encoding="utf-8"?>
<catalog_title>
 …
  <category scheme="http://api.netflix.com/categories/genres"
            label="Music &amp; Musicals" term="Music &amp; Musicals"></category>
  <category scheme="http://api.netflix.com/categories/genres/623"
            label="Animation for Grown-ups" term="Animation for Grown-ups"></category>
  <category scheme="http://api.netflix.com/categories/genres/2316"
            label="Contemporary Movie Musicals" term="Contemporary Movie Musicals"></category>
  <category scheme="http://api.netflix.com/categories/genres/343"
            label="Indie Dramas" term="Indie Dramas"></category>
  <category scheme="http://api.netflix.com/categories/genres/315"
            label="Indie Dramas" term="Indie Dramas"></category>
 …
</catalog_title>

On June 15th, 2011, these genres are going away, to be replaced by a new classification model. This new model will be more flexible and more well-tuned to the diverse expectations of a global movie-watching audience.

What this means for you as an API developer is that you should identify any parts of your applications that rely on the current genre structure and remove this dependency in preparation for the rollout of the new classification model. Details of this new model will soon follow here at http://developer.netflix.com/.

The playback_bookmark element will always be zero as of June 30

If you request the users/user_ID/title_states resource for an instant-watch title that the subscriber has (at least partially) watched, the record for such a title has (in API versions 1.5 and higher) included a <playback_bookmark> element. That element gave an offset, in seconds, into the title’s play time to indicate where the subscriber last stopped or paused play.

At the end of June, 2011, as a side-effect of Netflix system changes, the playback bookmark element will return a default value of zero whether or not the subscriber has played, paused, or stopped the title. This affects API versions 1.5 or higher.

Netflix may re-introduce this feature in a future release of the Netflix API, but for now you are advised to hide, disable, or remove any features of your applications that rely on the the <playback_bookmark> element.

New "Series" Model

Summary: Netflix is moving toward treating a television series as a unified object — a single title — rather than as a set of seasons. You may notice some changes in the data you work with through the Netflix API, and you may want to change some of the logic of your application to better harmonize with this new conceptualization of the television series.

Description

Netflix is moving toward treating a television series as a unified object — a single title — rather than as a set of seasons or discs. The set-of-seasons or set-of-discs model is more of an artifact of the way DVDs are published and marketed, whereas the series-as-a-singular-thing is closer to the natural way of how subscribers think of a television series.  You can already see this change emerging on the main Netflix site, and you may also note some changes in the underlying data to support this change.

Note that for some series with a particularly large number of titles (more than 200), the series may be broken up into more than one title — for instance: organized by decade.

Impact

Changes in API Requests and Responses

When you use the Netflix API to request the episodes associated with a series title, you will get a complete list of episodes for the series. This may be a larger list than you are used to getting for titles of this sort, and if your application intends to display information (such as the title state) for each episode, it will need to be prepared to use more (or bulkier) transmissions and more screen real estate in order to do so.

Episode titles will include information about the season number and episode number for each episode.

Here is an example response to a request for catalog/titles/series/70142415?v=2.0&expand=@episodes under the new model:

<catalog_title>
 <id>http://api.netflix.com/catalog/titles/series/70142415</id>
 <title short="The Sarah Silverman Program" regular="The Sarah Silverman Program"/>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/box_art" rel="http://schemas.netflix.com/catalog/titles/box_art" title="box art"/>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/synopsis" rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"/>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/short_synopsis" rel="http://schemas.netflix.com/catalog/titles/synopsis.short" title="short synopsis"/>
 <release_year>2007</release_year>
 <category scheme="http://api.netflix.com/categories/genres" label="Television" term="Television"/>
 <category scheme="http://api.netflix.com/categories/genres/2471" label="TV Sketch Comedies" term="TV Sketch Comedies"/>
 <category scheme="http://api.netflix.com/categories/genres/2197" label="TV Comedies" term="TV Comedies"/>
 <category scheme="http://api.netflix.com/categories/maturity_level" label="130" term="130"/>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/screen_formats" rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"/>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/cast" rel="http://schemas.netflix.com/catalog/people.cast" title="cast"/>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/seasons" rel="http://schemas.netflix.com/catalog/titles.seasons" title="seasons"/>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/episodes" rel="http://schemas.netflix.com/catalog/titles.programs" title="episodes">
  <catalog_titles>
   <number_of_results>22</number_of_results>
   <link href="http://api.netflix.com/catalog/titles/programs/190213/70137452" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 1: Officer Jay"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190214/70137456" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 1: Humanitarian of the Year"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190215/70137453" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 1: Positively Negative"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190216/70137454" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 1: Not Without My Daughter"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190217/70137455" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 1: Muffin' Man"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190218/70137451" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 1: Batteries"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190219/70137457" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 1: Bored of the Rings"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190220/70137460" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 1: Joan of Arf"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190221/70137459" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 1: Face Wars"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190222/70137458" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 1: Doodie"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190223/70137462" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 1: Ah, Men"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190224/70137461" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 1: Maid to Border"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180818/70137469" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: High, It's Sarah"/>
   <link href="http://api.netflix.com/catalog/titles/programs/190929/70137464" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: The Mongolian Beef"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180820/70137466" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: Making New Friends"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180821/70137468" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: Patriot Tact"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180822/70137463" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: Pee"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180823/70137465" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: There's No Place Like Homeless"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180824/70137467" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: Fetus Don't Fail Me Now"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180825/70137470" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: I Thought My Dad Was Dead, But It Turns Out He's Not"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180826/70137471" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: Kangamangus"/>
   <link href="http://api.netflix.com/catalog/titles/programs/180827/70137472" rel="http://schemas.netflix.com/catalog/title" title="The Sarah Silverman Program: Season 2: Vol. 2: Vow Wow"/>
  </catalog_titles>
 </link>
 <average_rating>3.0</average_rating>
 <link href="http://api.netflix.com/catalog/titles/series/70142415/similars" rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"/>
 <link href="http://www.netflix.com/Movie/The_Sarah_Silverman_Program/70142415" rel="alternate" title="web page"/>
 <link href="http://movi.es/VofWB" rel="http://schemas.netflix.com/catalog/title/ref.tiny" title="Tiny URL"/>
</catalog_title> 

Subscriber Expectations

Subscribers will come to expect that when they decide to "Add" a series to their queue, they will be adding the whole series — not just a season or a disc from the series. They will also expect, at the end of viewing details about one episode, to be given the choice to see the next episode in the series, without any additional clunkiness if this means passing over a (now-obsolete) season or disc boundary.

Subscribers may see changes to some of the information they have contributed. For instance if they formerly had ratings for multiple seasons of a series, these ratings will be consolidated into a single rating for the series as a whole. If they had formerly added certain seasons of a series to their queues, they may find these replaced in their queues by the series itself (if we've done this correctly as planned, the subscriber won't lose their place in the series during this switch).

API Rockstars Wanted

Netflix is the biggest consumer of the largest and most complex cloud computing environment, and is responsible for double-digit percentages of web traffic on a daily basis. The solutions we design define the cutting edge of consumer video provision. By joining our API team, you will be helping to fashion the state of the art for this space. As an engineer at Netflix, it won't be enough for you to be up-to-date on the latest standards and practices — you will need to look beyond them and help to explore the next steps of our industry in an ever-changing world where consumer expectations have a Moore's Law of their own.

Almost every day brings a new developer or partner to the Netflix API, and we often feel like we can't enable all the APIs we wish we could fast enough. To address both of those challenges, the Netflix API team is growing!

This is a developer forum — you are developers — you know other developers. Please help us find rockstars for each of these roles:

Interested parties can learn more about these positions and apply for them by using the job links above. For more information on working at Netflix, please see http://www.netflix.com/Jobs.

OData Catalog Updates

After working with the OData system for several days, we have made some improvements to the system - some of them will break existing code, but this should be our last update of that nature (although it remains in "preview" mode, and so could change in the future.

Changes:

  • The “Catalog” prefix has been removed from all entity sets. Therefore, “CatalogTitles” is now just “Titles”, “CatalogTitleGenres” is now just “TitleGenres”, and so on. This mirrors Netflix’s existing APIs, and also removes a bit of redundancy from the URL, since the root of the service is already “/Catalog/”.
  • The Title entity’s ID is no longer a GUID, but rather a generated string that comes from Netflix’s API.
  • The Person entity’s ID is no longer a GUID, but rather a generated number that comes from the Netflix’s API.
  • The catalog data now includes whether a title is available for instant watch in HD (“Catalog/Titles?$filter=Instant/HighDefinitionAvailable”), which Netflix is beginning to start providing more often.
  • The catalog data is now updated nightly to stay in sync with current Netflix data.

These changes should make the OData API more useful and consistent for developers to use.  All changes have been documented on the OData Catalog API page.

Have fun, and let us know how it works for you!


[ Page 1 of 4 | Next ]