Metadata Ingestion APIsShelf and Feed APIsSubscriber Activity APIs

Get Recommended Shelves

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

GET - /metax/3.0/shelf/{SUBSCRIBER_ID}

Header Paramater

Bearer Access Token

NOTE: Access Token here refers to the access authorization token.

URL Parameter

Subscriber ID (e.g.

Form Parameter

The type of algorithm(s) to use in creating these shelves. More than one algorithms can be specified as comma-separated list. Valid algo values are:
  • algo_auto (Automated MetaX selections)
  • algo_tp (Top picks for You)
  • algo_bw ( Because you watched)
  • algo_mp (Most Popular)
  • algo_lw (Last Watched)
  • algo_cw (Continue Watching)
  • algo_ra (Recently Added)
  • algo_tn (Trending)
  • algo_fv (My Favorites)
  • algo_mg (Micro genres)
  • algo_gn (Based on genre)
  • algo_sr (Based on last search results)
Default value: algo_auto Note that if you specify more than one algorithm values, then algo_auto cant be a part of that list.
The number of recommended shelves required for the subscriber. Integer value 1,2,3,etc. Default value: 0. This asks MetaX to choose a good number of shelves for the subscriber based on user profile..

Example Request URL

GET - http://__JTV_HOST__/metax/3.0/shelf/

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