Netflix REST API Reference

Netflix API 1.5 Programmer’s Guide: API Reference

This page is a reference guide to Netflix API 1.5 (this is distinct from the JavaScript API which is documented elsewhere). This page is divided into the following sections:

Getting Started with Netflix API: the varieties of Netflix API requests, common characteristics of all such requests, and how this reference guide is organized
Catalog Resource API Requests: Netflix API requests with which you get information about the Netflix catalog of instant-watch titles, about individual titles, or about actors, directors, and other people associated with titles
User Resource API Requests: Netflix API requests with which you retrieve or change information about a particular Netflix subscriber, such as their instant-watch queue or ratings
Security Resource API Requests: the authentication handshake and security signing process that the Netflix API requires from you in order to use it

Getting Started with Netflix API

Common Characteristics of REST Resources

The following characteristics apply to all Netflix API resources:

You access a resource by sending an HTTP request to the Netflix API server. The server replies with a response that either contains the data you requested, or a status indicator, or both.
All resources are located at http[s]://api.netflix.com/.
You request a particular resource by appending a particular path to this base URL that specifies the resource.
Most resource-specific parameters are optional, except for the oauth_ access control authentication parameters. See Authentication Overview to learn how to set those parameters correctly.
All resources may return any of the status codes listed in HTTP Status Codes. Other status or error codes that a particular resource might return are listed specifically in the section of this page that describes that resource.
On this page, when a portion of a URL, path, or parameter value is shown in italics, this indicates that you should replace the italicized value with a particular value appropriate to your request.

How to Use These Reference Entries

This page has reference entries for the various resources in the Netflix API 1.5. Each reference entry generally includes the following information:

the resource path (the part of the URL that specifies the particular resouce)
a list of the allowed and required parameters and a description of their possible values
a description of what the resource does
the HTTP verbs you can use when accessing the resource (the GET verb is the default, if no other verbs are explicitly listed)
the sorts of responses that the resource returns, and one or more response examples
any status codes that the Netflix API might return that are specific to this resource (see HTTP Status Codes for an overview of those status codes that are common to all resources)

Catalog Resources

Catalog resources that you can retrieve include the complete Netflix instant-watch title catalog, details about particular titles in the catalog, and information about people (such as actors and directors) whose works are represented in the Netflix title catalog. You can search for such resources in a variety of ways by using the Netflix API. On this page, the Catalog resources are divided into the following task categories:

Searching the Title Catalog
Retrieving Title Details
Searching for People (for instance, cast members or directors)

Searching the Title Catalog

You use the following resource paths to search the Netflix catalog for titles. To access a resource, append the resource path to the base URL. For example, to use the catalog/titles resource, access http://api.netflix.com/catalog/titles.

catalog/titles: Search for a title in the instant-watch title catalog.
catalog/titles/autocomplete: Retrieve a list of potential title matches by using a partial title string
catalog/titles/index: Retrieve a list of titles in the Netflix instant-watch title catalog

Catalog Titles

Use the catalog titles resource to search the instant-watch title catalog for titles of movies and television series. You search for catalog tiles at the URL http://api.netflix.com/catalog/titles. This resource takes the following parameters:

Parameter	Description
`term`	Set this to 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`	Set this to a zero-based offset into the list that results from the query. By using this with the `max_results` parameter, you can request successive pages of search results.
`max_results`	Set this to 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.
OAuth access control	Consumer key + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Returns the matching titles as a series of <catalog_title> records in relevance order, and the total number of results in <results_per_page>.

Results Example

The following is an example of part of a response to a catalog/titles request:

<catalog_titles>
  <number_of_results>1140</number_of_results>
  <start_index>0</start_index>
  <results_per_page>10</results_per_page>
  <catalog_title>
  <id>http://api.netflix.com/catalog/titles/movies/60021896</id><title short="Star" regular="Star"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/60021896.jpg"  
	medium="http://alien2.netflix.com/us/boxshots/small/60021896.jpg"  
	large="http://alien2.netflix.com/us/boxshots/large/60021896.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/60021896/synopsis"  
	rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>2001</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="NR"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/60021896/cast"  
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60021896/directors"  
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60021896/format_availability"  
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60021896/screen_formats" rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link
  <link href="http://api.netflix.com/catalog/titles/movies/60021896/languages_and_audio" rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
  <average_rating>1.9</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/60021896/similars" rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://www.netflix.com/Movie/Star/60021896" rel="alternate" title="webpage"></link>
  </catalog_title>
  <catalog_title>
  <id>http://api.netflix.com/catalog/titles/movies/17985448</id><title short="Lone Star" regular="Lone Star"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/17985448.jpg" medium="http://alien2.netflix.com/us/boxshots/small/17985448.jpg" large=""></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/synopsis" rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1996</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="R"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/cast" rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/directors" rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/awards" rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/format_availability" rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/screen_formats" rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/languages_and_audio" rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
  <average_rating>3.7</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/17985448/similars" rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://www.netflix.com/Movie/Lone_Star/17985448" rel="alternate" title="webpage"></link>
  </catalog_title>
</catalog_titles>

Catalog Titles Autocomplete

Use the catalog titles autocomplete resource to search the catalog 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). You access this resource at http://api.netflix.com/catalog/titles/autocomplete. This resource takes the following parameters:

Parameter	Description
`term`	Set this to the partial search term you want to use to search for title matches in the catalog.
`oauth_consumer_key`	Set this to your consumer key, a.k.a. "API key" (required).

Results

Netflix API returns a list of movie and television title names that match your partial search text. You can then pass these title names to the title search resource to conduct the actual search.

Note that this resource searches only the "short" version of the title for the partial text. When you later search the catalog using the regular title search resource, you may receive results that match either the "short" or "regular" versions of the title.

Results Example

The following is an example response to catalog/autocomplete:

<autocomplete>
  <autocomplete_item>
    <title short="Step Brothers"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Step Into Liquid"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Step Up"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Step Up 2 the Streets"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Step Your Game Up: Part 5: The Journal Story"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Stephanie Daley"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Stephen King's The Mist"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Stephen Sondheim's Putting It Together"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="Stepmom"></title>
  </autocomplete_item>
  <autocomplete_item>
    <title short="The Stepford Wives"></title>
  </autocomplete_item>
</autocomplete>

Catalog Titles Index

Use the catalog titles index resource to retrieve a complete index of all instant-watch titles in the Netflix catalog. The catalog is large, so it will take some time to download. You can minimize the download time by sending a Accept-Encoding: gzip header with your request and then decompressing the response on your end.

You may find this useful if you have your own movie or TV catalogs and you want to find corresponding titles in the Netflix catalog. The index data that Netflix API returns through this method includes titles, release dates (year of release), production studio name, and top cast members. You can use such data to interlink titles. In addition, the data includes Netflix title URLs and availability windows. Each title entry in the returned data also includes an update timestamp, which indicates the last time Netflix updated the title data in its catalog.

You access this index via http://api.netflix.com/catalog/titles/index.

You must be authorized in order to access AMG (All Movie Guide) or TMS (TMS Entertainment, Ltd.) identifiers. If you are a direct licensee of AMG's or TMS's data products, let Neflix know and we will give you the required authorization.

This resource takes the following parameters:

Parameter	Description
`include_amg`	Set this to "true" to include AMG identifiers in title index items (requires authorization).
`include_tms`	Set this to "true" to include TMS identifiers in title index items (requires authorization).
OAuth access control	Consumer key + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Netflix API returns an index of all titles in the Netflix instant-watch catalog.

Results Example

The following is an example of a portion of a catalog/titles/index response:

<catalog_title_index>
  <title_index_item>
	<id>http://api.netflix.com/catalog/titles/movies/512381</id>
	<updated>1217404229</updated>
	<link href="http://api.netflix.com/catalog/people/20001977"  
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Anna Paquin"></link>
	<link href="http://api.netflix.com/catalog/people/23599" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Dana Delany"></link>
	<link href="http://api.netflix.com/catalog/people/21741" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Jeff Daniels"></link>
	<release_year>1996</release_year>
	<link href="http://www.netflix.com/Movie/Fly_Away_Home/512381" rel="alternate" title="web page"></link>
	<external_ids>
	<id rel="http://schemas.netflix.com/catalog/id.upc">0043396824393</id>
	<id rel="http://schemas.netflix.com/catalog/id.upc">0043396060463</id>
	<id rel="http://schemas.netflix.com/catalog/id.amg">V   154424</id>
	</external_ids>
  </title_index_item>
  <title_index_item>
	<id>http://api.netflix.com/catalog/titles/movies/517905</id>
	<link href="http://api.netflix.com/catalog/people/100637" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Elijah Wood"></link>
	<link href="http://api.netflix.com/catalog/people/98401"
	  rel="http://schemas.netflix.com/catalog/person.actor" title="George Wendt"></link>
	<link href="http://api.netflix.com/catalog/people/34976" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Isabel Glasser"></link>
	<link href="http://api.netflix.com/catalog/people/21028" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Jamie Lee Curtis"></link>
	<link href="http://api.netflix.com/catalog/people/34396" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Mel Gibson"></link>
	<release_year>1992</release_year>
	<link href="http://www.netflix.com/Movie/Forever_Young/517905" rel="alternate" title="web page"></link>
	<external_ids>
	  <id rel="http://schemas.netflix.com/catalog/id.upc">0085391257127</id>
	  <id rel="http://schemas.netflix.com/catalog/id.amg">V    18235</id>
	</external_ids>
  </title_index_item>
</catalog_title_index>

You can also use the 2.0 version of the API to retrieve a full version of the instant-watch catalog that is more consistent with that used in the main Netflix site. To do this, send an OAuth-signed request to:

http://api.netflix.com/catalog/titles/full?v=2.0

That URL will return a redirect to a location where you can fetch the full catalog. Note also that the redirect may itself sometimes point to another redirect, so please allow for that possibility when you write code to fetch this resource.

Title Details

Use the resources described in this section to retrieve details for specific instant-watch catalog titles. The API consists of a set of subresources within the catalog/titles resource path type that returns all details for the requested title.

Note: Whenever you make a API request that returns a list of titles, you can find the URLs that you use to retrieve the title's details by looking in the part of the response that references the title. The links within the title record in the response contain the URLs that you can use to retrieve a title's details.

Here are some example title detail retrieval paths for different types of titles:

http://api.netflix.com/catalog/titles/movies/title_id: returns details about a specific movie title
http://api.netflix.com/catalog/titles/series/series_id: returns details about a specific television series
http://api.netflix.com/catalog/titles/series/series_id/seasons/season_id: returns details about season collections for a specific television series
http://api.netflix.com/catalog/titles/programs/program_id: returns details about a specific television program

Use resource paths like those to retrieve details about a particular catalog title. A title can be a movie, a television series, a television series by season, a single television program, or a disc. Each resource returns the details appropriate to the requested title type. These resources take the following parameter:

Parameter	Description
OAuth access control	Consumer key + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Netflix API returns the details associated with the specified title. The actual details that it returns vary according to the type of the title. The tables below indicate which details are returned for the different types of titles.

For titles that are movies, the response can include the following data:

Movie Data	Description
Title (short, regular, and sortable versions)	the title of the movie (ay be in a shortened form, the complete title, or a version normalized for sorting)
Synopsis (short and regular versions)	a summary of the movie (the short form is appropriate for situations where screen real estate is limited)
Release year	the original release date for the movie
MPAA rating	the voluntary rating system (G, PG, PG-13, R, and NC-17) from the Motion Picture Association of America
TV rating	the rating system for television programs (see What do the ratings like "PG" and "NR" mean?)
Cast	the actors in the cast, with links to their data in the people resource database
Director	the director of the movie
Length	the length of the movie in seconds
Box art references (small, medium, and large)	the artwork from the cover of the DVD case, in three different sizes
Popularity rating	the 1- to 5-star rating of the movie, based on those Netflix subscribers who have rated the movie
Awards	the industry awards and nominations for the movie, if any
Bonus materials	an additional DVD with related content
Screen format	the width to height ratio for normal viewing of the movie
Language and sound	the language and Dolby digital mode in which the movie was recorded
Netflix web site URL	the Netflix page that shows the details of the movie
Official movie site URL	the studio's web page for the movie
Related titles	links to other movies in the series, if appropriate

For titles that are television program series and seasons, the response can include the following data:

Television Program Data	Description
Title (short, regular, and sortable versions)	the title of the program (can be in a shortened form, the complete title, or as a version normalized for sorting)
Synopsis (short and regular versions)	a summary of the program's season (the short form is appropriate for situations where screen real estate is limited)
Release year	the original release date for the beginning of the program's season
MPAA rating	the voluntary rating system (G, PG, PG-13, R, and NC-17) from the Motion Picture Association of America
TV rating	the rating system for television programs (see What do the ratings like "PG" and "NR" mean?)
Cast	the actors in the cast with links to their data in the people resource database
Director	the director of the program
Length	the length of the entire program in seconds
Box art references (small, medium, and large)	the artwork from the cover of the DVD case, in three different sizes
Popularity rating	the 1- to 5-star rating of the program, based on those Netflix subscribers who have rated it
Awards	the industry awards and nominations for the program, if any
Bonus materials	an additional DVD with related content
Screen format	the width to height ratio for normal viewing of the program
Language and sound	the language and Dolby digital mode in which the program was recorded
Netflix web site URL	the Netflix page that shows the details of the program
Official program site URL	the studio's web page for the program
Series links	links to other programs in the series
Season links	links to other programs in the season
Program links	links to other episodes of the program

Results Example

The following is an example of a response to a series search:

<catalog_title>
  <id>http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522</id>
  <title short="The Office: Season 1" regular="The Office: Season 1"/>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/70023522.jpg"
	medium="http://alien2.netflix.com/us/boxshots/small/70023522.jpg"  
	large="http://alien2.netflix.com/us/boxshots/large/70023522.jpg"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/synopsis"
	rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"/>
  <release_year>2005</release_year>
  <category scheme="http://api.netflix.com/categories/tv_ratings" label="TV-14"/>
  <runtime>8700</runtime>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/format_availability"
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/screen_formats"
	rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/cast"
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/directors"
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/languages_and_audio"
	rel="http://schemas.netflix.com/catalog/titles/languages_and_audio"
	title="languages and audio"/>
  <average_rating>4.3</average_rating>
  <link href="http://api.netflix.com/catalog/titles/series/70023522"
	rel="http://schemas.netflix.com/catalog/titles.series" title="series"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/episodes"
	rel="http://schemas.netflix.com/catalog/programs" title="episodes"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/previews"
	rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"/>
  <link href="http://api.netflix.com/catalog/titles/series/70023522/seasons/70023522/similars"
	rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"/>
  <link href="http://www.nbc.com/nbc/The_Office/"
	rel="http://schemas.netflix.com/catalog/titles/official_url" title="official webpage"/>
  <link href="http://www.netflix.com/Movie/The_Office_Season_1/70023522" rel="alternate"
	title="webpage"/>
</catalog_title>

Title Similars

Use this resource to retrieve a list of titles similar to a particular title resource. The similars resource URL can be found in the response of any title resource and will have a URL like the following: http://api.netflix.com/catalog/titles/type/title_id/similars. This resource takes the following parameters:

Parameter	Description
`start_index`	The zero-based offset into the results of the query. When you use this with the `max_results` parameter, you can request successive pages of search results.
`max_results`	The maximum number of results to return. This number cannot be greater than 500. If you do not specify `max_results`, the default value is 25.
OAuth access control	Consumer key + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Netflix API returns a list of titles that it determines to be similar to the title whose ID you referenced in the URL path.

Results Example

The following is an example of part of a response that might be returned by this resource.

<catalog_titles>
  <number_of_results>120</number_of_results>
  <start_index>0</start_index>
  <results_per_page>2</results_per_page>
  <catalog_title>
  <id>http://api.netflix.com/catalog/titles/movies/60003959</id>
  <title short="Bird" regular="Bird"></title>
  <etag>515873819112</etag>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/60003959.jpg"  
	medium="http://alien2.netflix.com/us/boxshots/small/60003959.jpg"  
	large="http://alien2.netflix.com/us/boxshots/large/60003959.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/synopsis"
	rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1988</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="R"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/cast"
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/directors"
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/awards"
	rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/format_availability"
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/screen_formats"
	rel="http://schemas.netflix.com/catalog/titles/screen_formats"
	title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/languages_and_audio"
        rel="http://schemas.netflix.com/catalog/titles/languages_and_audio"
	title="languages and audio"></link>
  <average_rating>3.4</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/60003959/previews"
	rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
  <link href="http://www.netflix.com/Movie/Bird/60003959" rel="alternate"
	title="webpage"></link>
  </catalog_title>
  <catalog_title>
  <id>http://api.netflix.com/catalog/titles/movies/70019224</id>
	<title short="Hotel Rwanda" regular="Hotel Rwanda"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/70019224.jpg"
	  medium="http://alien2.netflix.com/us/boxshots/small/70019224.jpg"
	  large="http://alien2.netflix.com/us/boxshots/large/70019224.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/synopsis"
	rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>2005</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings"
	label="PG-13"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/cast"
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/directors"
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/awards"
	  rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/format_availability"
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/screen_formats"
	rel="http://schemas.netflix.com/catalog/titles/screen_formats"
	title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/languages_and_audio"
	rel="http://schemas.netflix.com/catalog/titles/languages_and_audio"
	title="languages and audio"></link>
  <average_rating>4.2</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/70019224/previews"
	rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
  <link href="http://www.netflix.com/Movie/Hotel_Rwanda/70019224"
	rel="alternate" title="webpage"></link>
  </catalog_title>
</catalog_titles>

Searching for People

This section covers the API resources that you use to retrieve details about cast members, directors, and other people associated with the titles in the Netflix catalog.

`catalog/people`

Use this resource to search for people in the catalog by their name or a portion of their name. This resource takes the following parameters:

Parameter	Description
`term`	Set this to the word or term in the person's name to search for in the catalog.
`start_index`	Set this to the zero-based offset into the results of the query. When you use this with the `max_results` parameter, you can request successive pages of search results.
`max_results`	Set this to the maximum number of results to return. This number cannot be greater than 500. If you do not specify `max_results`, the default value is 25.
OAuth access control	Consumer key + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Netflix API returns results that include catalog title entries for titles that involve people that match the specified name. Results also include references to person details. Each person resource will have a URL like the following: http://api.netflix.com/catalog/people/person_id.

Results Example

The following is an example from a response to a catalog/people request:

<people>
  <number_of_results>1452</number_of_results>
  <start_index>0</start_index>
  results_per_page>2</results_per_page>
  <person>
	<id>http://api.netflix.com/catalog/people/152672</id>
	<name>Penélope Cruz</name>
	<bio><![CDATA[Born April 28, 1974, in Madrid, Spain, Penélope Cruz began reenacting TV commercials when she was a toddler and studied classical ballet during her youth. Her big break came at age 15 when she beat out hundreds of girls at a talent agency audition.<p>Cruz captured audiences' attention with her roles in Jamón, Jamón and Belle Epoque (both 1992). In 1999, her work with director Pedro Almodóvar in All About My Mother brought the actress worldwide recognition.<p>Fluent in Spanish, Italian, French and English, Cruz continues to work in American and international productions, appearing in such films as All the Pretty Horses (2000) and Vanilla Sky (2001). Her turn in Volver (2006) brought an Oscar nod, and she took home the statue two years later for her supporting performance in Vicky Cristina Barcelona. Cruz added Golden Globe and Oscar nominations to her résumé for her role in the 2009 musical Nine.]]></bio>
	<link href="http://api.netflix.com/catalog/people/152672/filmography"
	  rel="http://schemas.netflix.com/catlog/person/filmography" title="filmography"></link>
	<link href="http://www.netflix.com/RoleDisplay/Penelope_Cruz/152672" rel="alternate" title="webpage"></link>
  </person>
  <person>
	<id>http://api.netflix.com/catalog/people/20064096</id>
	<name>Valerie Cruz</name>       
	<link href="http://api.netflix.com/catalog/people/20064096/filmography"
	  rel="http://schemas.netflix.com/catlog/person/filmography" title="filmography"></link>
	<link href="http://www.netflix.com/RoleDisplay/Valerie_Cruz/20064096" rel="alternate" title="webpage"></link>
  </person>
</people>

Person Details

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. Each person resource will have a URL like the following: http://api.netflix.com/catalog/people/person_id. This resource takes the following parameter:

Parameter	Description
OAuth access control	Consumer key + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

For the person you specify by means of the person ID in the path, Netflix API returns a biography and a list of all titles with which that person is associated.

Results Example

The following is an example response:

<person>  
  <id>http://api.netflix.com/catalog/people/152672</id>  
  <name>Pen&#233;lope Cruz</name>  
  <bio><![CDATA[Born April 28, 1974, in Madrid, Spain, Penélope Cruz began reenacting TV commercials when she was a toddler and studied classical ballet during her youth. Her big break came at age 15 when she beat out hundreds of girls at a talent agency audition.<p>Cruz captured audiences' attention with her roles in Jamón, Jamón and Belle Epoque (both 1992). In 1999, her work with director Pedro Almodóvar in All About My Mother brought the actress worldwide recognition.<p>Fluent in Spanish, Italian, French and English, Cruz continues to work in American and international productions, appearing in such films as All the Pretty Horses (2000) and Vanilla Sky (2001). Her turn in Volver (2006) brought an Oscar nod, and she took home the statue two years later for her supporting performance in Vicky Cristina Barcelona. Cruz added Golden Globe and Oscar nominations to her résumé for her role in the 2009 musical Nine.]]></bio>  
  <link href="http://api.netflix.com/catalog/people/152672/filmography"  
	rel="http://schemas.netflix.com/catlog/person/filmography" title="filmography"></link>  
  <link href="http://www.netflix.com/RoleDisplay/Penelope_Cruz/152672" rel="alternate" title="webpage"></link>  
</person>

User Resources

Use the User resources in Netflix API to access information about a specific Netflix subscriber (or "user"). Use these resources to retrieve or modify information concerning a subscriber's viewing history, ratings, and recommendations. The User resources include the queue management resources, which let you retrieve and manipulate items in a subscriber's instant-watch queue. The User resources also provide a list of Atom feed URLs that applications and browsers can access. These feeds have security tokens embedded within their URLs and so they can be consumed by applications that cannot authenticate using the OAuth protocol.

This page divides the User resources into the following task categories:

Users, Feeds and Title States

Use the following resources to retrieve information about subscribers (users), subscriber activity feeds, and the relationship between a subscriber and any title (title states):

users/user_id
users/current
users/user_id/feed
users/user_id/title_states

`users`

Returns information about the subscriber with the specified user ID. A user resource has a URL like: http://api.netflix.com/users/user_id. This resource takes the following parameter:

Parameter	Description
OAuth access control	Consumer key + access token + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Netflix API returns the name of the subscriber whose user ID you specified in the path, and that subscriber's associated queues and other subscriber information.

Results Example

The following is a sample response to this request:

<user>
  <user_id>T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-</user_id>
  <first_name>Jane</first_name>
  <last_name>Smith</last_name>
  <can_instant_watch>true</can_instant_watch>
  <link href="http://api.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/queues"
	rel="http://schemas.netflix.com/queues" title="queues"></link>
  <link href="http://api.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/rental_history"
	rel="http://schemas.netflix.com/rental_history" title="rental history"></link>
  <link href="http://api.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/recommendations"
	rel="http://schemas.netflix.com/recommendations" title="recommendations"></link>
  <link href="http://api.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/title_states"
	rel="http://schemas.netflix.com/title_states" title="title states"></link>
  <link href="http://api.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/ratings"
	rel="http://schemas.netflix.com/ratings" title="ratings"></link>
</user>

`users/current`

Current User (reflection)

This resource returns a link to the user resource for an authenticated subscriber for whom you have an access token. You can use this resource to get the link without having to extract the subscriber's user ID from the OAuth access token response. This resource takes the following parameter:

Parameter	Description
OAuth access control	Consumer key + access token + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

The call returns a single "link" element that contains the URL that you can use to make Netflix API calls to access additional resources for this subscriber.

Example Results

The following is a smaple of a plain XML (POX) response to this request:

<resource>
  <status_code>200</status_code> 
  <link href="http://api.netflix.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-" rel="http://schemas.netflix.com/user.current" title="current user"></link>
</resource>

`users/user_id/feeds`

Many subscriber-related resources are available to you as feeds. You can get a list of the subscriber's feeds by using the resource found at http://api.netflix.com/users/user_id/feeds.

When you access a resource as a feed, you do not have to supply any OAuth security token since the URL for the feed includes an embedded security token as a parameter. This embedded security token is valid for as long as the subscriber allows your application to access the Netflix service on the subscriber's behalf.

This resource takes the following parameters:

Parameter	Description
`output`	Set the value of this parameter to "`opml`" if you want your response in OPML (Outline Processor Markup Language, an XML format for outlines) rather than XML (which is the default format).
OAuth access control	Consumer key + access token + signature. (Required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Netflix API returns a list of URLs of all feeds available for the specified user.

Results Example

The following is a sample of an XML response to this request:

<resource>
  <link href="http://api.netflix.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-/queues/instant?feed_token=T1u.tZSbY9311F5W0C5eVQXaJ49.KBapZdwjuCiUBzhoJ_.lTGnmES6JfOZbrxsFzf&amp;oauth_consumer_key=v9s778n692e9qvd83wfj9t8c&amp;output=atom"
	rel="http://schemas.netflix.com/feed.queues.instant" title="Instant Queue"></link>
  <link href="http://api.netflix.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-/queues/instant?feed_token=T1u.tZSbY9311F5W0C5eVQXaJ49.KBapZdwjuCiUBzhoJ_.lTGnmES6JfOZbrxsFzf&amp;oauth_consumer_key=v9s778n692e9qvd83wfj9t8c&amp;output=atom&amp;sort=date_added"  
	rel="http://schemas.netflix.com/feed.queues.instant.recent" title="Recent Additions to Instant Queue"></link>
  <link href="http://api.netflix.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-/rental_history/watched?feed_token=T1Bj0aYRbYBu0y0AvVq6CMe63ZEiGhb6RcYu3d7apdMFfK_Dlg_qWxDSHaSPlAu2P3aS4KROIgGOJh4kZUZtJAvg--&amp;oauth_consumer_key=v9s778n692e9qvd83wfj9t8c&amp;output=atom"
        rel="http://schemas.netflix.com/feed.rental_history.watched" title="Titles Watched Recently"></link>
  <link href="http://api.netflix.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-/recommendations?feed_token=T1PeXieDTki.jbRFpFRArljzw4fe.iTem2XYfwbv6BosZadXZFIxEQ.M8wf_8XvouevwsyL3B9mS8OB25crS0r0g--&amp;oauth_consumer_key=v9s778n692e9qvd83wfj9t8c&amp;output=atom"
        rel="http://schemas.netflix.com/feed.recommendations" title="Recommendations"></link>
  <link href="http://api.netflix.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-/ratings/title/actual?feed_token=T1XOCp5.fEsLoqfkNPGxwkJdE_ZK.ryzqz7w26JW520B5mT4tTAGUqjBmpN9KZHIhkjuPBSafYj9cGmR8e7LPEBg--&amp;oauth_consumer_key=v9s778n692e9qvd83wfj9t8c&amp;output=atom"
        rel="http://schemas.netflix.com/feed.ratings" title="Ratings"></link>
</resource>

The next example shows the response as returned in OPML format:

<opml version="2.0">
  <head>
	<title>Personal Netflix Feeds</title>
	<dateCreated>Sat, 18 Jun 2005 12:11:52 GMT</dateCreated>
  </head>
  <body>
	<outline text="Instant Queue" title="Instant Queue" type="rss"
         xmlUrl="http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/queues/instant?feed_token=xyz&sort=date_added"/>
	<outline text="Recent Additions to Instant Queue" title="Recent Additions to Instant Queue" type="rss"
         xmlUrl="http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/queues/instant?feed_token=xyz&sort=date_added"/>
	<outline text="Titles Watched Recently" title="Titles Watched Recently" type="rss" 
	 xmlUrl="http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/rental_history/watched?feed_token=xyz"/>
	<outline text="Recommendations" title="Recommendations" type="rss"  
	 xmlUrl="http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/recommendations?feed_token=xyz"/>
	<outline text="Ratings" title="Ratings" type="rss"
         xmlUrl="http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/ratings/title/actual?feed_token=xyz"/>
  </body>
</opml>

Title States

Use the title states resource to help determine a subscriber's rental options for a particular title or titles. Each response contains a link to the subscriber's status vis-a-vis that title or titles.

A link to the title states resource can be found in any user response as http://api.netflix.com/users/user_id/title_states.

The response includes these details:

if the title is in the instant watch queue (In Instant Queue)
if not in the instant queue, the appropriate action either to add the title to that queue (Add) or play the title (Play)

This resource takes the following parameters:

Parameter	Description
`title_refs`	One or more comma-delimited catalog title URLs for which to retrieve the title state. You can request up to 500 titles' states in a single request.
OAuth access control	Consumer key + access token + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Netflix API returns a series of records that indicate the relationship between the subscriber and one or more titles.

Results Example

The following is an example response to this request:

<title_states>
  <link href="http://api.netflix.com/catalog/titles/movies/70036143"
	rel="http://schemas.netflix.com/id" title="title"></link>
  <title_state>
	<link href="http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant"
	  rel="http://schemas.netflix.com/queues/instant" title="instant queue"></link>
	<category scheme="http://api.netflix.com/catalog/titles/format" label="instant"></category>
	<category scheme="http://api.netflix.com/catalog/titles/title_states" label="play"></category>
  </title_state>
</title_states>

Managing Queues

Use the queue management resources to retrieve and manipulate the contents of a subscriber's instant-watch queue. You can use these resources (with the HTTP POST and DELETE verbs) to add and remove catalog titles to and from a queue, and also to move the title's location within the queue. You also use these resources (with the GET verb) to retrieve queue details, such as the current titles in the queue, their respective positions, and their availability

Use the following HTTP methods to invoke the queue management resources:

users/userID/queues: Returns the contents of a subscriber's instant-watch queue.
users/userID/queues/instant: GET returns details about a subscriber's instant watch queue. POST adds or moves titles within a subscriber's instant-watch queue.
users/userID/queues/instant/available: Returns availability details of titles in a subscriber's instant-watch queue.
users/userID/queues/instant/available/entryID: GET retrieves details about the entry from the subscriber's instant-watch queue. DELETE deletes the specified entry from the subscriber's instant watch queue.
users/userID/queues/instant/saved: Returns the saved status of an entry in a subscriber's instant-watch queue.
users/userID/queues/instant/saved/entryID: GET retrieves details about the saved entry from the subscriber's instant-watch queue. DELETE deletes the specified entry from the subscriber's instant-watch queue.

`users/userID/queues`

`users/userID/queues/instant`

`users/userID/queues/instant/available`

`users/userID/queues/instant/available/entryID`

`users/userID/queues/instant/saved`

`users/userID/queues/instant/saved/entryID`

These resources return the subscriber's instant-watch queues. Responses include titles that are available for play and saved pre-release titles. Also included are the queue entry URLs for each item in the queue.

Note that the updated timestamp in Atom-formatted responses always equals the time that the queue data was requested.

Invoke these resources using either the GET, POST, or DELETE verbs. See Updating a Queue for more information on using the queue management resources with the POST and DELETE verbs.

The following parameters apply to each queue resource when you use the GET verb.

Parameter	Description
`sort`	Use this to specify the sort order for the queue entries. Sort order may be by `queue_sequence`, `date_added`, or `alphabetical`. The default sort order, if you do not specify one, is `queue_sequence`. Note: The `queue_order` is always `alphabetical` for a saved disc queue that does not have numeric positions.
`start_index`	Set this to the zero-based offset into the results for the query. Use this parameter with `max_results` to request successive pages of search results.
`max_results`	Set this to the maximum number of results you want. This number cannot be greater than 500. If you do not specify `max_results`, the default value is 25.
`updated_min`	Set this to filter returned items, allowing through only those items with updated times greater than or equal to the value you set for `updated_min`. You can specify this value in Unix time format (seconds since epoch) or in the format defined by RFC 3339 (as used by the Atom feed standard).
OAuth access control	Consumer key + access token + signature. (Required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

When you request this resource with the GET verb, it returns details about the subscriber's instant-watch queues, including available and saved pre-release titles, plus links to resources that describe each title in the queue.

Results Example

This example is part of a response showing queue information retrieval:

<queue>
 <etag>819873819117</etag>
 <number_of_results>220</number_of_results>
 <start_index>0</start_index>
 <results_per_page>3</results_per_page>
 <queue_item>
  <id>http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available/1/251454</id>
  <position>1</position>
  <link href="http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available"
        rel="queue_ref" title="Available Queue"></link>
  <category scheme="http://api.netflix.com/categories/queue_availability" label="available_now"></category>
  <updated>1204284910</updated>
  <category scheme="http://api.netflix.com/catalog/titles/format" label="Instant"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/251454" rel="http://schemas.netflix.com/id"  
        title="title"></link>
  <title short="An American in Paris" regular="An American in Paris"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/251454.jpg"  
           medium="http://alien2.netflix.com/us/boxshots/small/251454.jpg"  
           large="http://alien2.netflix.com/us/boxshots/large/251454.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/synopsis"  
        rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1951</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="UR"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/screen_formats"  
        rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/languages_and_audio"  
        rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
  <average_rating>3.7</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/previews"  
        rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/251454/similars"  
        rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://www.netflix.com/Movie/An_American_in_Paris/251454"  
        rel="alternate" title="webpage"></link>
 </queue_item>

 <queue_item>
  <id>http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available/2/70038486</id>
  <position>2</position>
  <link href="http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available"
        rel="queue_ref" title="Available Queue"></link>
  <category scheme="http://api.netflix.com/categories/queue_availability" label="available_now"></category>
  <updated>1204284933</updated>
  <category scheme="http://api.netflix.com/catalog/titles/format" label="Instant"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486" rel="http://schemas.netflix.com/id"  
        title="title"></link>
  <title short="Ben-Hur: Collector's Edition" regular="Ben-Hur: Collector's Edition"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/70038486.jpg"  
           medium="http://alien2.netflix.com/us/boxshots/small/70038486.jpg"  
           large="http://alien2.netflix.com/us/boxshots/large/70038486.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/synopsis"  
        rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1959</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="NR"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/screen_formats"  
        rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/languages_and_audio"  
        rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
  <average_rating>4.1</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/previews"  
        rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70038486/similars"  
        rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://www.netflix.com/Movie/Ben-Hur_Collector_s_Edition/70038486" rel="alternate" title="webpage"></link>
 </queue_item>

 <queue_item>
  <id>http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/saved/70071617</id>
  <link href="http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/saved"  
        rel="http://schemas.netflix.com/queues" title="Saved Queue"></link>
  <category scheme="http://api.netflix.com/categories/queue_availability" label="saved"></category>
  <updated>1217949743</updated>
  <category scheme="http://api.netflix.com/catalog/titles/format" label="Instant"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/70071617" rel="http://schemas.netflix.com/id"  
        title="title"></link>
  <title short="Triangle" regular="Triangle"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/70071617.jpg"  
           medium="http://alien2.netflix.com/us/boxshots/small/70071617.jpg"  
           large="http://alien2.netflix.com/us/boxshots/large/70071617.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/70071617/synopsis"  
        rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>2007</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="NR"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/70071617/cast"
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70071617/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/70071617/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <average_rating>3.3</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/70071617/similars"  
        rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://www.netflix.com/Movie/Triangle/70071617" rel="alternate" title="webpage"></link>
 </queue_item>

</queue>

Updating a Queue

You use a subset of the queue management resources to add titles to an instant-watch queue, change the queue order, or remove titles from a queue. This section provides additional information for using these resources with the POST and DELETE verbs.

`users/userID/queues/instant/available/entryID`

`users/userID/queues/instant/saved/entryID`

Use these resources to delete titles from an instant-watch queue. Delete a catalog title from a queue by executing an HTTP DELETE operation on the queue entry URL (the entry identifier) for any title. The response to the DELETE operation lists the queue entry URLs for each queue entry.

Results

The resource response lists the queue entry URLs for each deleted queue entry.

users/userID/queues/instant

Use this resource with the POST verb to add catalog titles to the instant-watch queues or to move titles within a queue. Add the title to the queue by doing a POST operation and pass the title URL. Optionally, you may also pass in the position of the title within the queue.

These resources automatically add the title to the saved or available queue, depending on the title's availability. To see the availability for a title and correlate that with the subscriber's account settings, check the user/userID/title_states resource for the title. (See users/userID/title_states.)

If a title already exists in a queue, then you can use the position parameter to modify the existing queue entry.

The ETag value you pass to the operation indicates the last time that the queue was read. (Netflix API returned this ETag value to you with the response to your most recent queue request.) The POST operation fails if the queue has been updated since the creation of the ETag value you are passing in. Each successful POST response returns a new ETag value.

The following parameters apply to these queue resources when you use them with the POST verb. This resource takes the following parameters:

Parameter	Description
`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.
OAuth access control	Consumer key + access token + signature. (Required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

If your request is successful, Netflix API returns the queue entries that you 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 returns 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.

Managing Rental History

Use the rental_history resource and its subresources to retrieve a subscriber's viewing history. You can retrieve information about titles the subscriber has recently instant-watched.

`users/userID/rental_history`

`users/userID/rental_history/watched`

These resources return a list of titles that reflect a subscriber's viewing history. The response results are sorted by the time each title was entered into each list.

This resource takes the following parameters:

Parameter	Description
`start_index`	Set this to the zero-based offset into the results for the query. Use this parameter with `max_results` to request successive pages of search results.
`max_results`	Set this to the maximum number of results to return. This number cannot be greater than 500. If you do not specify `max_results`, the default value is 25.
`updated_min`	Set this to filters returned items, allowing through only those items with updated timestamps greater than or equal to the passed value of `updated_min`. Specify this value either in Unix time format (seconds since epoch) or in the format defined by RFC 3339 (as used by the Atom feed standard).
OAuth access control	Consumer key + access token + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

This resource returns a list of up to ten of the most recent titles that reflect a subscriber's viewing history.

Results Example

The following is an example response to this request that lists recently watched titles:

<rental_history>
<url_template>http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/
  rental_history?{-join|&amp;|start_index|max_results}</url_template>
<number_of_results>155</number_of_results>
<start_index>0</start_index>
<results_per_page>2</results_per_page>
<rental_history_item>
  <id>http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/rental_history/watched/70063995</id>
  <watched_date>1219775019</watched_date>
  <viewed_time>00:00:26</viewed_time>
  <updated>1219775019</updated>
  <category scheme="http://api.netflix.com/categories/rental_states" label="Watched" term="Watched"></category>
  <link href="http://api.netflix.com/catalog/titles/programs/70063995" rel="http://schemas.netflix.com/id"  
	title="title"></link>
  <title short="Pink Panther: Think Before You Pink" regular="The Pink Panther Classic Cartoon Collection: 
	Think Before You Pink" episode_short="Think Before You Pink"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/70035020.jpg"  
	medium="http://alien2.netflix.com/us/boxshots/small/70035020.jpg"  
	large="http://alien2.netflix.com/us/boxshots/large/70035020.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/programs/70063995/synopsis"  
	rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1969</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="NR" term="NR"></category>
  <link href="http://api.netflix.com/catalog/titles/programs/70063995/cast"  
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/programs/70063995/directors"  
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/programs/70063995/format_availability"  
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/programs/70063995/similars"  
	rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://api.netflix.com/Movie/The_Pink_Panther_Classic_Cartoon_Collection_Think_Before_You_Pink/70063995" 
	rel="alternate" title="web page"></link>
</rental_history_item>  
<rental_history_item>
  <id>http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/rental_history/watched/860591</id>
  <watched_date>1219779112</watched_date>
  <viewed_time>00:01:23</viewed_time>
  <updated>1217418632</updated>
  <category scheme="http://api.netflix.com/categories/rental_states" label="Watched" term="At Home"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/860591" rel="http://schemas.netflix.com/id" title="title"></link>
  <title short="Platoon" regular="Platoon"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/860591.jpg"
           medium="http://alien2.netflix.com/us/boxshots/small/860591.jpg"
           large="http://alien2.netflix.com/us/boxshots/large/860591.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/860591/synopsis"
    	rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1986</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="R" term="R"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/860591/cast"
    	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/860591/directors"
    	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
    <link href="http://api.netflix.com/catalog/titles/movies/860591/awards"
    	rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
    <link href="http://api.netflix.com/catalog/titles/movies/860591/format_availability"
    	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
    <link href="http://api.netflix.com/catalog/titles/movies/860591/screen_formats"
    	rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen  formats"></link>
    <link href="http://api.netflix.com/catalog/titles/movies/860591/languages_and_audio"
    	rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
    <average_rating>4.0</average_rating>
    <link href="http://api.netflix.com/catalog/titles/movies/860591/similars"
    	rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
    <link href="http://api.netflix.com/Movie/Platoon/860591" rel="alternate" title="web page"></link>
</rental_history_item>
<rental_history_item>
  <id>http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/rental_history/watched/60000540</id>
  <watched_date>1219792112</watched_date>
  <viewed_time>00:01:09</viewed_time>
  <updated>1217404229</updated>
  <category scheme="http://api.netflix.com/categories/rental_states" label="Watched" term="Returned"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540" rel="http://schemas.netflix.com/id"
    	title="title"></link>
  <title short="Braveheart" regular="Braveheart"></title>
  <box_art small="http://alien2.netflix.com/us/boxshots/tiny/60000540.jpg"
    	medium="http://alien2.netflix.com/us/boxshots/small/60000540.jpg"
    	large="http://alien2.netflix.com/us/boxshots/large/60000540.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/synopsis"
    	rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1995</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="R" term="R"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/cast"
    	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/directors"
    	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/awards"
    	rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/format_availability"
    	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/screen_formats"
    	rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/languages_and_audio"
    	rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
  <average_rating>4.3</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/60000540/similars"
    	rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://api.netflix.com/Movie/Braveheart/60000540" rel="alternate" title="web page"></link>
</rental_history_item>
<link href="http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/rental_history/watched"
      rel="http://schemas.netflix.com/rental_history/watched" title="watched"></link> </rental_history>

User Title Ratings

You use the user title rating resources to retrieve a subscriber's rating for an individual movie or television series season. You can retrieve the subscriber's actual rating or predicted rating for each title. You also use these resources to create new ratings for a subscriber.

users/userID/ratings/title: Returns a subscriber's rating for a title.
users/userID/ratings/title/actual: Creates a new rating for a subscriber
users/userID/ratings/title/actual/ratingID: Updates an existing subscriber rating
users/userID/ratings/title/predicted: Returns the predicted ratings for a subscriber

`users/userID/ratings/title`

This resource returns a subscriber's rating for the specified movie title or television series. The response includes the subscriber's actual rating resource URL and the rating value, if set, otherwise the Netflix prediction of how the user would rate this movie or television series. The results omit actual ratings results for queries on multiple title identifiers if the rating values are not set for any given title. This resource takes the following parameters:

Parameter	Description
`title_refs`	The Netflix API URL (for example: "`http://api.netflix.com/catalog/titles/70099480`"), or a comma-delimited list of such URLs, representing the title(s) for which to retrieve ratings. You may request a maximum of 500 ratings.
OAuth access control	Consumer key + access token + signature. (Required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

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.

Results Example

The following is an example response to this request:

<ratings>
   <ratings_item>
   <user_rating>3.0</user_rating>
   <predicted_rating>4.5</predicted_rating>
   <updated>1217949743</updated>
   <id>http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/ratings/titles/60036359</id>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359"
	 rel="http://schemas.netflix.com/id" title="title"></link>
   <title short="Schindler's List" regular="Schindler's List"></title>
   <box_art small="http://alien2.netflix.com/us/boxshots/tiny/60036359.jpg"
	 medium="http://alien2.netflix.com/us/boxshots/small/60036359.jpg"
	 large="http://alien2.netflix.com/us/boxshots/large/60036359.jpg"></box_art>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/synopsis"
	 rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
   <release_year>1993</release_year>
   <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="R"></category>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/cast"
	 rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/directors"
	 rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/awards"
	 rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/format_availability"
	 rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/screen_formats"
	 rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/languages_and_audio"
	 rel="http://schemas.netflix.com/catalog/titles/languages_and_audio"
	 title="languages and audio"></link>
   <average_rating>4.5</average_rating>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/previews"
	 rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036359/similars"
	 rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
   <link href="http://www.netflix.com/Movie/Schindler_s_List/60036359" rel="alternate"
	 title="webpage"></link>
   </ratings_item>
   <ratings_item>
   <predicted_rating>4.0</predicted_rating>
   <id>http://api.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/ratings/titles/60036356</id>
   <link href="http://api.netflix.com/catalog/titles/movies/60036356"
	 rel="http://schemas.netflix.com/id" title="title"></link>
   <title short="Children of Paradise" regular="Children of Paradise"></title>
   <box_art small="http://alien2.netflix.com/us/boxshots/tiny/60036356.jpg"
	 medium="http://alien2.netflix.com/us/boxshots/small/60036356.jpg"
	 large="http://alien2.netflix.com/us/boxshots/large/60036356.jpg"></box_art>
   <link href="http://api.netflix.com/catalog/titles/movies/60036356/synopsis"
	 rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
   <release_year>1946</release_year>
   <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="UR"></category>
   <link href="http://api.netflix.com/catalog/titles/movies/60036356/cast"
	 rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036356/directors"
	 rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
   <link href="http://api.netflix.com/catalog/titles/movies/60036356/awards"
	 rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
   <average_rating>4.0</average_rating>
   <link href="http://www.netflix.com/Movie/Children_of_Paradise/60036356" rel="alternate"
	 title="webpage"></link>
  </ratings_item>
</ratings>

`users/userID/ratings/title/actual`

Use this resource to create a new rating for a subscriber or to access subscriber ratings.

Invoke this resource using the GET or POST methods.

Access a Rating

Request this resource with the GET operation to individually access a subscriber's rating for the specified movie title or television series. The response includes a list of the subscriber's actual rating resource URLs and the rating values, if set. The results omit actual ratings results for queries on multiple title identifiers if the rating values are not set for any given title.

When you access this resource with the GET operation, the following parameters apply:

Parameter	Description
`title_refs`	Set this to the Netflix API URL (for example: "`http://api.netflix.com/catalog/titles/70099480`"), or a comma-delimited list of such URLs, representing the title(s) for which to retrieve ratings. You may request a maximum of 500 ratings.
OAuth access control	Consumer key + access token + signature. (Required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

When you request this resource with the GET verb, the Netflix API returns a list of rating values and URLs for the designated subscriber.

Create a Rating

You can create a new rating for a subscriber by requesting this resource with the POST verb. You set the following parameters for the resource within the POST:

Parameter	Descriptioin
`title_ref`	Set this to The Netflix API URL (for example: "`http://api.netflix.com/catalog/titles/70099480`") of the title to be rated.
`rating`	Set this to the rating value, which must be an integer from 1 to 5 or the strings `not_interested` or `no_opinion`.
OAuth access control	Consumer key + access token + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

When you request this resource with the POST verb, the Netflix API returns the rating identifier and the URL to the newly created rating.

`users/userID/ratings/title/actual/ratingID`

Use this resource to update an existing rating for a subscriber or to access a specific subscriber rating.

Invoke this resource using the GET or PUT verbs.

Access a Rating

Access this resource with the GET verb to read a subscriber's actual rating for the specified movie title or television series.

Update an Existing Rating

You can update an existing rating for a subscriber by accessing this resource with the PUT verb. You PUT to the URL of the specific actual rating subresource (the URL includes the user id and the rating id) and set the following parameters for the resource:

Parameter	Description
`rating`	A rating value, which must be an integer from 1 to 5, or `not_interested` .
OAuth access control	Consumer key + access token + signature. (Required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Updates the subscriber's rating to the new value or returns the subscriber's ratings for the designated catalog title.

`users/userID/ratings/title/predicted`

Use this resource to access a subscriber's predicted ratings individually. The response returns Netflix's prediction of how the subscriber would rate a set of titles, and includes the resource URLs and the rating values, if set. This resource takes the following parameters:

Parameter	Description
`title_refs`	Set this to The Netflix API URL (for example: "`http://api.netflix.com/catalog/titles/70099480`"), or a comma-delimited list of such URLs, representing the title(s) for which you want to retrieve predicted ratings. You may request a maximum of 500 predictions.
OAuth access control	Consumer key + access token + signature (required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Retrieving Recommendations

You use the recommendations resource to see Netflix's catalog title recommendations for a subscriber, based on a subscriber's viewing history.

`users/userID/recommendations`

Use this resource to retrieve a list of catalog title recommendations for a subscriber. The recommendations are based upon the subscriber's ratings and rental history. This resource takes the following parameters:

Parameter	Description
`start_index`	Set this to the zero-based offset into the results for the query. Use this parameter with `max_results` to request successive pages of search results.
`max_results`	Set this to the maximum number of results to return. This number cannot be greater than 500. If you do not specify `max_results`, the default value is 25.
OAuth access control	Consumer key + access token + signature. (Required). See Authentication Overview for instructions on how to form the mandatory OAuth access control authentication parameters.

Results

Returns up to 25 recommendations for a specified user. The response includes the related title URLs.

Results Example

The following is an example response to this request:

<recommendations>
 <recommendation>
  <predicted_rating>4.1</predicted_rating>
  <id>http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/recommendations/243547</id>
  <link href="http://api.netflix.com/catalog/titles/movies/243547" rel="http://schemas.netflix.com/id"  
	title="title"></link>
  <title short="All the President's Men" regular="All the President's Men"></title>
  <box_art small="http://cdn-0.nflximg.com/us/boxshots/tiny/243547.jpg"
	   medium="http://cdn-0.nflximg.com/us/boxshots/small/243547.jpg"  
	   large="http://cdn-0.nflximg.com/us/boxshots/large/243547.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/synopsis"  
        rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1976</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="PG" term="PG"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/screen_formats"  
        rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/languages_and_audio"  
        rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
  <average_rating>4.0</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/243547/similars"  
        rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://www.netflix.com/Movie/All_the_President_s_Men/243547" rel="alternate"  
        title="webpage"></link>
 </recommendation>

 <recommendation>
  <predicted_rating>4.1</predicted_rating>
  <id>http://api.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/recommendations/262839</id>
  <link href="http://api.netflix.com/catalog/titles/movies/262839" rel="http://schemas.netflix.com/id"  
        title="title"></link>
  <title short="Apocalypse Now" regular="Apocalypse Now"></title>
  <box_art small="http://cdn-0.nflximg.com/us/boxshots/tiny/262839.jpg"  
           medium="http://cdn-0.nflximg.com/us/boxshots/small/262839.jpg"  
           large="http://cdn-0.nflximg.com/us/boxshots/large/262839.jpg"></box_art>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/synopsis"  
        rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"></link>
  <release_year>1979</release_year>
  <category scheme="http://api.netflix.com/catalog/titles/mpaa_ratings" label="R" term="R"></category>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/screen_formats"  
        rel="http://schemas.netflix.com/catalog/titles/screen_formats" title="screen formats"></link>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/languages_and_audio"  
        rel="http://schemas.netflix.com/catalog/titles/languages_and_audio" title="languages and audio"></link>
  <average_rating>4.0</average_rating>
  <link href="http://api.netflix.com/catalog/titles/movies/262839/similars"  
        rel="http://schemas.netflix.com/catalog/titles.similars" title="similars"></link>
  <link href="http://www.miramax.com/apocalypsenow/" 
        rel="http://schemas.netflix.com/catalog/titles/official_url" title="official webpage"></link>
  <link href="http://www.netflix.com/Movie/Apocalypse_Now/262839" rel="alternate" title="webpage"></link>
 </recommendation>
</recommendations>

Security Resources

You use the security resources to retrieve the credentials you need to access Netflix subscriber data on behalf of the subscriber and with the subscriber's explicit authorization. The security resources are based on the OAuth Core 1.0 protocol. Please refer to Authentication Overview for complete details on how to use these resources. The security resources, unless otherwise noted, are available from the same domain as the other resources (http://api.netflix.com/).

The following security resources are available:

The following illustration shows the process of using these resources to retrieve the credentials you need to access a Netflix subscriber's data:

`oauth/request_token`

Use this resource to obtain a request token from Netflix so that your application can request an access token with which it can access a subscriber's Netflix account on behalf of that subscriber. You can only use a request token in one request for an access token, regardless of the outcome of that request. If your access token request fails for any reason, you must use a new request token for any subsequent request. This resource takes the following parameters:

Parameter	Description
`oauth_consumer_key`	Set this to your consumer key, or "API key."
`oauth_signature_method`	Set this to the signature method that you use to sign the request. The only allowable signature method is `HMAC-SHA1`, which is a signature algorithm that is defined in RFC 2104 ("HMAC: Keyed-Hashing for Message Authentication"). The signature base string holds the text. The key is the concatenated values (after encoding) of the consumer secret and the token secret, separated by an ampersand (`&`), even if the token secret is empty.
`oauth_signature`	Set this to the signature that you generated with the HMAC algorithm: a consistent, reproducible function of the concatenation of the request elements into a single string.
`oauth_timestamp`	Set this to the timestamp of the request, expressed as the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value must be a positive integer and must be equal or greater than the timestamp used in previous requests. This, combined with the nonce value, guards against replay attacks.
`oauth_nonce`	Set this to a randomly-generated string. This approach demonstrates that a particular request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel, such as HTTP.
`oauth_version`	(optional) If present, the value must be 1.0 (which is also the default if this parameter is omitted).

Results

Returns an unauthorized request token, a token secret, and the application name.

Results Example

oauth_token=bzb8aexfpvz56m4da82gksvf&oauth_token_secret=Zp4eJkFMRMeG&application_name=myfilmclub

`https://api-user.netflix.com/oauth/login`

Authenticates a subscriber and allows your application to request permission to access Netflix services on the subscriber's behalf.

Note: This API resource is an ordinary web page. It is not a REST resource.

This resource takes the following parameters:

Parameter	Description
`name`	the subscriber's name
`password`	the subscriber's Netflix password
`accept_tos`	`TRUE` indicates that user has consented to the terms of service
`application_name`	the name of your application that you used when you generated your OAuth keys
`oauth_consumer_key`	your consumer key (or "API key")
`oauth_token`	the unauthorized request token that you obtained from `oauth/request_token`
`oauth_callback`	(optional) a URL that you want Netflix to redirect the subscriber back to after obtaining subscriber authorization

Results

Returns an authorized request token as a URL parameter to the callback.

Results Example

oauth_token=aqa8xeaprto56m4da82gksvf

`oauth/access_token`

Once you have requested an unauthorized access token and used it to send the user to Netflix to authorize your application and give you an authorized access token, you can use it to access this resource and thereby gain access to a user's protected resources on Netflix. This resource takes the following parameters:

Parameter	Description
`oauth_consumer_key`	Set this to your consumer key, or "API key".
`oauth_signature_method`	Set this to the signature method that you use to sign the request. The only allowable value for this parameter is "`HMAC-SHA1`", which is a signature algorithm that is defined in RFC 2104 ("HMAC: Keyed-Hashing for Message Authentication"). The key is the concatenated values (after encoding) of the consumer secret and the token secret, separated by an ampersand (`&`) even if the token secret is empty.
`oauth_signature`	Set this to the signature you generate by means of the HMAC algorithm: a consistent, reproducible function of a concatenation of the request elements into a single string.
`oauth_timestamp`	Set this to the timestamp of this request, expressed as the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value must be a positive integer and mst be equal or greater than the timestamp used in previous requests. This helps to prevent replay attacks.
`oauth_nonce`	Set this to a randomly-generated string. This demonstates that a particular request has never been made before and guards against replay attacks when requests are made over a non-secure channel, such as HTTP.
`oauth_version`	(optional) If present, value must be 1.0 (which is also the default if this parameter is not present).

Results

Returns the access token, a token secret, and the subscriber's user ID.

Results Example

oauth_token=bzb8aexfpvz56m4da82gksvf&oauth_token_secret=Zp4eJkFMRMeG&user_id=asLDga2z94n12f7sa-

version 114 as of 8 months ago by David Gross

Previous: Common Netflix REST API Tasks
Up: Introduction to Netflix API Documentation
Next: Branding Requirements

25 Comments

Mike – 3 years ago

In the section on "catalog/titles/index" it says that preauthorization is required to retreive the AMG or TMS IDs. What does that mean I need to use and authorized request token? If so, why is that required to get to these external IDs. If not, how do I obtain preauthorization?
Michael Hart – 3 years ago

Mike, you just need proof that you are a licensee of AMG's or TMS's data products and we can enable you.
whurlston – 3 years ago

Would being on the approved applications list for Schedules Direct count? http://www.schedulesdirect.org/approvedsoftware
kscott – 3 years ago

I'm hoping someone can assist me with the correctly accessing the Catalog Resources. For the passed few days I've been fighting with search titles. I need to better understand how I'm suppose for create the signature required search through the titles.

Do I need exactly what is need to generate the signature, and if the order of the parameters are important when constructing the finally http request?

Any help would be greatly appreciated possible with an example.

Thanks in advance
Michael Hart – 3 years ago

@whurlston, sorry but you need to be a direct licensee of AMG
Michael Hart – 3 years ago

@kscott, the Authentication Overview has what you need. Check out the last section. There is an improved version of this documentation coming in the next day or so.
Emerj – 3 years ago

Where do I find Netflix player API documentation?
Michael Hart – 3 years ago

There is no player API at this time. You can invoke the Netflix player in a browser using the JavaScript API.
Ketan – 3 years ago

Hello,

I'm trying to access catalog/titles/index resource. It seems include_amg and include_tms are required params. What if I don't have the preauthorization ?

How should I proceed ?

Thank you.
Ketan Kulkarni
Michael Hart – 3 years ago

There aren't really any required parameters in the API.
worksology – 3 years ago

How would you request all of a user's ratings? Being required to request ratings for specific titles seems crazy (in isolation). Is there any way to just ask for a user's ratings, regardless of title? If not, is there a chance this may be added to the API eventually?
txt2trade – 3 years ago

Is there any way to access a user's account on their behalf without going through the oauth/login page? I am writing a server-side application and my users do not have access to a browser, so I have no way to execute this step.
Michael Hart – 3 years ago

@worksology, we didn't want to expose ratings en masse without providing mechanisms for sync'ing back the changes after modifications. It seemed like we might be doing users a disservice by potentially creating different repositories of ratings that can't sync with each other. We're looking making the system improvements we need to support this soon, e.g. adding timestamps for all ratings changes, not just the last 20 updates.
Michael Hart – 3 years ago

@ txt2trade, answered your question here: http://developer.netflix.com/forum/read/32122
Cyrus Najmabadi – 3 years ago

The documentation is a bit unclear:
position - The position within the queue in which to insert or move the title.

Is that position 0 based, or 1 based?
mikey – 3 years ago

It is 1 based
Cyrus Najmabadi – 3 years ago

I don't appear to be getting an etag back after a delete. Is that intentional? If so, how can i make my next call appropriately after performing a delete? Do i have to rerequest the queue just to get its etag?
houdoken – 3 years ago

Is there a way to access the "Instant Watching Activity" (reported here: https://www.netflix.com/WiViewingActivity?lnkctr=ph_watched) via RSS or otherwise? I'm looking to pull Instant titles watched but not necessarily explicitly added to one's queue. Would also love to get viewing date more specific than just calendar date--YYYY/MM/DD HH:MM:SS, ideally. The viewing duration, as listed in the URL above, would also be grand. Any ideas? If this isn't available, where might I go to formally request future inclusion of said data?
Thanks in advance!
Michael Hart – 3 years ago

Check out the rental_history resource for watched title history. It should have all the innfomation you need.
MDiamond – 3 years ago

What kind of guarantees (if any) does Netflix provide about the liveness of the links in the box art element? Is it safe to store that information and access them again later (as in hours, days, weeks, or even months) or is it likely the urls will change over time?
Michael Hart – 3 years ago

The closest thing to a guarantee is our default date retention policy in the TOS, which says you shouldn't cache data (with some exceptions) longer than twenty-four hours. That being said, we don't have any plans to change box art locations, but anything is possible in the future.
Matt Ackeret – 3 years ago

Isn't the Results for this:
users/userID/rental_history
and the others incorrect?

It says:
Results
Returns a list of up to ten of the most recent titles that reflect a subscriber's rental history.

Shouldn't it really say
Returns a list of up to 500 of the most recent titles that reflect a subscriber's rental history.
?
pillars5 – 2 years ago

For
https://api-user.netflix.com/oauth/login

Parameters:
application_name Your application name returned by oauth/request_token
oauth_consumer_key Your Netflix API key

are also required.
pillars5 – 2 years ago

For
oauth/access_token

Results should be:
Returns the access token, a token secret, and the user_id.

Results Example:
oauth_token=bzb8aexfpvz56m4da82gksvf&oauth_token_secret=Zp4eJkFMRMeG&user_id=aReallyLongString
diracleo – 4 months ago

How do you specify that you only want streamable (watch it now) results returned?

Please sign in to post a comment.