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-public.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

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-public.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/streaming
Retrieve a list of instant-watch titles in the Netflix title catalog
catalog/titles/dvd
Retrieve a list of DVD-by-mail titles in the Netflix 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-public.netflix.com/catalog/titles. This resource takes the following parameters:

ParameterDescription
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-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="NR"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/60021896/cast"  
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/60021896/directors"  
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/60021896/format_availability"  
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.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-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="R"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/17985448/cast" rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/17985448/directors" rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/17985448/awards" rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/17985448/format_availability" rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.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-public.netflix.com/catalog/titles/autocomplete. This resource takes the following parameters:

ParameterDescription
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 resources to retrieve a complete index of all instant-watch or DVD-by-mail titles in the Netflix catalog. The catalogs are 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 limited information about 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-public.netflix.com/catalog/titles/streaming (for instant-watch titles) or http://api-public.netflix.com/catalog/titles/dvd (for DVD-by-mail titles).

This resource takes the following parameters:

ParameterDescription
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 or DVD-by-mail catalog.

Results Example

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

<catalog_title_index>
  <title_index_item>
	<id>http://api-public.netflix.com/catalog/titles/movies/512381</id>
	<updated>1217404229</updated>
	<link href="http://api-public.netflix.com/catalog/people/20001977"  
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Anna Paquin"></link>
	<link href="http://api-public.netflix.com/catalog/people/23599" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Dana Delany"></link>
	<link href="http://api-public.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>
	</external_ids>
  </title_index_item>
  <title_index_item>
	<id>http://api-public.netflix.com/catalog/titles/movies/517905</id>
	<link href="http://api-public.netflix.com/catalog/people/100637" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Elijah Wood"></link>
	<link href="http://api-public.netflix.com/catalog/people/98401"
	  rel="http://schemas.netflix.com/catalog/person.actor" title="George Wendt"></link>
	<link href="http://api-public.netflix.com/catalog/people/34976" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Isabel Glasser"></link>
	<link href="http://api-public.netflix.com/catalog/people/21028" 
	  rel="http://schemas.netflix.com/catalog/person.actor" title="Jamie Lee Curtis"></link>
	<link href="http://api-public.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>
	</external_ids>
  </title_index_item>
</catalog_title_index>

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-public.netflix.com/catalog/titles/movies/title_id
returns details about a specific movie title
http://api-public.netflix.com/catalog/titles/series/series_id
returns details about a specific television series
http://api-public.netflix.com/catalog/titles/series/series_id/seasons/season_id
returns details about season collections for a specific television series
http://api-public.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:
ParameterDescription
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 DataDescription
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 DataDescription
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-public.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-public.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-public.netflix.com/categories/tv_ratings" label="TV-14"/>
  <runtime>8700</runtime>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/series/70023522/seasons/70023522/cast"
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"/>
  <link href="http://api-public.netflix.com/catalog/titles/series/70023522/seasons/70023522/directors"
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"/>
  <link href="http://api-public.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-public.netflix.com/catalog/titles/series/70023522"
	rel="http://schemas.netflix.com/catalog/titles.series" title="series"/>
  <link href="http://api-public.netflix.com/catalog/titles/series/70023522/seasons/70023522/episodes"
	rel="http://schemas.netflix.com/catalog/programs" title="episodes"/>
  <link href="http://api-public.netflix.com/catalog/titles/series/70023522/seasons/70023522/previews"
	rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"/>
  <link href="http://api-public.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-public.netflix.com/catalog/titles/type/title_id/similars. This resource takes the following parameters:

ParameterDescription
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-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="R"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/60003959/cast"
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/60003959/directors"
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/60003959/awards"
	rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/60003959/format_availability"
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.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-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings"
	label="PG-13"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70019224/cast"
	rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70019224/directors"
	rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70019224/awards"
	  rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70019224/format_availability"
	rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.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:

ParameterDescription
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-public.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-public.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-public.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-public.netflix.com/catalog/people/20064096</id>
	<name>Valerie Cruz</name>       
	<link href="http://api-public.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-public.netflix.com/catalog/people/person_id. This resource takes the following parameter:

ParameterDescription
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-public.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-public.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. 

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

Users and Title States

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

  • users/user_id
  • users/current
  • 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-public.netflix.com/users/user_id. This resource takes the following parameter:

ParameterDescription
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-public.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/queues"
	rel="http://schemas.netflix.com/queues" title="queues"></link>
  <link href="http://api-public.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/recommendations"
	rel="http://schemas.netflix.com/recommendations" title="recommendations"></link>
  <link href="http://api-public.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/title_states"
	rel="http://schemas.netflix.com/title_states" title="title states"></link>
  <link href="http://api-public.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:

ParameterDescription
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-public.netflix.com/users/T1tareQFowlmc8aiTEXBcQ5aed9h_Z8zdmSX1SnrKoOCA-" rel="http://schemas.netflix.com/user.current" title="current user"></link>
</resource>

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-public.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:

ParameterDescription
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-public.netflix.com/catalog/titles/movies/70036143"
	rel="http://schemas.netflix.com/id" title="title"></link>
  <title_state>
	<link href="http://api-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant"
	  rel="http://schemas.netflix.com/queues/instant" title="instant queue"></link>
	<category scheme="http://api-public.netflix.com/catalog/titles/format" label="instant"></category>
	<category scheme="http://api-public.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.

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.

ParameterDescription
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-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available/1/251454</id>
  <position>1</position>
  <link href="http://api-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available"
        rel="queue_ref" title="Available Queue"></link>
  <category scheme="http://api-public.netflix.com/categories/queue_availability" label="available_now"></category>
  <updated>1204284910</updated>
  <category scheme="http://api-public.netflix.com/catalog/titles/format" label="Instant"></category>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="UR"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/251454/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/251454/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/251454/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/251454/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/movies/251454/previews"  
        rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
  <link href="http://api-public.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-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available/2/70038486</id>
  <position>2</position>
  <link href="http://api-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/available"
        rel="queue_ref" title="Available Queue"></link>
  <category scheme="http://api-public.netflix.com/categories/queue_availability" label="available_now"></category>
  <updated>1204284933</updated>
  <category scheme="http://api-public.netflix.com/catalog/titles/format" label="Instant"></category>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="NR"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70038486/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70038486/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70038486/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70038486/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/movies/70038486/previews"  
        rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
  <link href="http://api-public.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-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/saved/70071617</id>
  <link href="http://api-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/queues/instant/saved"  
        rel="http://schemas.netflix.com/queues" title="Saved Queue"></link>
  <category scheme="http://api-public.netflix.com/categories/queue_availability" label="saved"></category>
  <updated>1217949743</updated>
  <category scheme="http://api-public.netflix.com/catalog/titles/format" label="Instant"></category>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="NR"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70071617/cast"
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/70071617/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.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-public.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:

ParameterDescription
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.

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:

ParameterDescription
title_refs The Netflix API URL (for example: "http://api-public.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-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/ratings/titles/60036359</id>
   <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="R"></category>
   <link href="http://api-public.netflix.com/catalog/titles/movies/60036359/cast"
	 rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
   <link href="http://api-public.netflix.com/catalog/titles/movies/60036359/directors"
	 rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
   <link href="http://api-public.netflix.com/catalog/titles/movies/60036359/awards"
	 rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
   <link href="http://api-public.netflix.com/catalog/titles/movies/60036359/format_availability"
	 rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
   <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/movies/60036359/previews"
	 rel="http://schemas.netflix.com/catalog/titles/previews" title="previews"></link>
   <link href="http://api-public.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-public.netflix.com/users/T1DonaZPk00Jl39mXvKMpOsJ344BJtLQAh4SyvxWAV4Tk-/ratings/titles/60036356</id>
   <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="UR"></category>
   <link href="http://api-public.netflix.com/catalog/titles/movies/60036356/cast"
	 rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
   <link href="http://api-public.netflix.com/catalog/titles/movies/60036356/directors"
	 rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
   <link href="http://api-public.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:

ParameterDescription
title_refs Set this to the Netflix API URL (for example: "http://api-public.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:

ParameterDescriptioin
title_ref Set this to The Netflix API URL (for example: "http://api-public.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:

ParameterDescription
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:

ParameterDescription
title_refs Set this to The Netflix API URL (for example: "http://api-public.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

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.

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:

ParameterDescription
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-public.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/recommendations/243547</id>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="PG" term="PG"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/243547/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/243547/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/243547/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/243547/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.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-public.netflix.com/users/T1CnHNCdr7uoFZoFoTtlXxm7H_FbtMI3eaW.7rcu.ssX8-/recommendations/262839</id>
  <link href="http://api-public.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-public.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-public.netflix.com/catalog/titles/mpaa_ratings" label="R" term="R"></category>
  <link href="http://api-public.netflix.com/catalog/titles/movies/262839/cast"  
        rel="http://schemas.netflix.com/catalog/people.cast" title="cast"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/262839/directors"  
        rel="http://schemas.netflix.com/catalog/people.directors" title="directors"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/262839/awards"  
        rel="http://schemas.netflix.com/catalog/titles/awards" title="awards"></link>
  <link href="http://api-public.netflix.com/catalog/titles/movies/262839/format_availability"  
        rel="http://schemas.netflix.com/catalog/titles/format_availability" title="formats"></link>
  <link href="http://api-public.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-public.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-public.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-public.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:

ParameterDescription
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:

ParameterDescription
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:

ParameterDescription
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-