This API provides the capability to create an arbitrary number of recommended shelves for a user. Replace {SUBSCRIBER_ID} by the unique id of the user to get shelves for the user.

The number and type of shelves returned by the API is controlled by two parameters:

• algo: Select the type of algorithm(s) that you want for this set of shelves. For example, if algo=algo_bw, all returned recommended shelves will be of type “Because you watched XYZ”. The individual titles XYZ for each shelf are automatically determined based on the subscriber’s profile.

  You can choose to specify more than one algorithm in a single request using a comma-separated list of algorithms. E.g. algo=algo_bw,algo_cw. In such a case, all shelves created will be of one of the types listed in the list. A comma-separate list behaves like an algo_auto (which can choose any type of algorithm for a given shelf), but with the restriction that that it use only one of the listed algorithm.

• count: The maximum number of shelves (using the specified algo) to return. For example, if algo=algo_bw and count=2, then two different “Because you watched” shelves will be returned – one could be “Because you watched Avatar” and second “Because you watched Titanic”.

  Note that, count is the maximum number of shelves to be returned — not the exact number of shelves. This is because there are several instances where specified number of shelves of a particular type may not exist. For example, for algo_lw (Last Watched) type shelf, there is exactly one valid shelf for a user. So a count=2 specified with algo=algo_lw will return only one shelf. Similarly, if a request for 2 “Because you watched” shelves arrives, but the subscriber is new and has only watched 1 movie till now, the API will return only one shelf corresponding to the movie user watched.

An app can mix-and-match different type and number of shelves as per requirements. For example, 5 separate requests for 1 algo_cw (Continue Watching), 3 algo_mg (Micro Genres), 4 algo_bw (Because you Watched …), 1 algo_tp (Top Picks for You), 1 algo_mp (Most Popular) can be used to create a 10-shelf layout for a user. While each individual response will return the shelves in order of their ranking for the user (highest ranking first), the final ordering of shelves from different requests is for the requestor to decide.

Alternatively, a mix-and-match can be achieved by providing all required algorithms in a single request as a comma-separated list. E.g. algo=algo_cw,algo_mg,algo_bw,algo_tp,algo_mp&count=10 will also result in a 10-shelf stack. However, the number of shelves of each type is not guaranteed.

By default (using algo_auto), the API will return the best shelves for a user from the entire shelf-universe.

Make all calls for a single shelf type for a user in a single request with appropriate count. Since the API is stateless, it may return same shelf for a user if two separate requests are made for the same algo type. For example, if two requests for algo=algo_bw with count=1 for a user arrive separately, the API may return “Because you watched Avatar” for both requests for the same user. However, combining the two requests into one with count=2&algo=algo_bw will return two different “Because you watched” shelves in the response.

Resource URL

Example Request URL

Example Return

The response of a invalid authorization access call ( Status #401) will look as follows:-

To see how to get access token - (see Getting Access Tokens)

The response of an ERROR in authorization access call ( Status #404) will look as follows:-

HTTP Status 404