Personalization API

The Personalization API provides a number of ways to personalize the experience for every one of your users, keeping them engaged with the digital content or items they love most. The Personalization API exposes the unique recommendations generated by Cortex using the behavioral information submitted to the Behavioral API.

GET requests are made to Vidora’s Personalization API via the API methods listed below. Each method specifies the optional and required parameters that should be submitted with each request.

If you’ve built a request to any of the User Recommendations, Personalization Item Similarities, Popularity, or Trending endpoints, you can use the Test Your Personalization API Filters tool in your Cortex Account to check how many items satisfy your filters and are available to serve the request. The more available items, the better results can be personalized or optimized. With this tool, you can gauge the effect of adding or removing filters in order to strike the right balance between breadth and specificity of content.

As mentioned in the section on Signing API Requests, you will need to append a signature to each request unless this requirement has been disabled for your account.

If your business has a media library of series or shows with episodic content, check out the section below on Working with Series and Episodes in the APIs to understand when the APIs will return either a series or an episode.

URI Escaping Special Characters

For a number of the methods outlined below, there are parameters which can take a list of values. For example, when querying Recommendations for a specific user, you may want to filter the list of returned items to only include those for a specific list of categories. In this case, you will pass over a list of categories within a single parameter. In these instances, it’s required to URI Escape the list to ensure proper functionality of the API Call.

Example Request
Here is an example using the User Recommendations API call covered in the next section. Our goal is to return only Recommended items that fall under the categories comedy, drama, or action. Here is how to properly URI Escape this parameter.

Not Escaped: category=comedy&drama&action
Properly Escaped: category=comedy%26drama%26action

And here is how that would appear in the full API Call

http://api.vidora.com/v1/users/<USER_ID>/recommendations?api_key=<YOUR_KEY>&category=comedy%26drama%26action&limit=3&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

User Recommendations

Returns the top recommended content or item ids for the given user. Optionally, recommendations may be filtered by standard parameters (listed below), or by custom parameters corresponding to any metadata tags associated with your content or items. The User Recommendations API call also supports pagination, enabling you to deploy personalized infinite scroll by loading recommendations in real time for each user.

You may test the number of items available to serve your request with the Test Your Personalization API Filters tool in your Cortex Account.
Request

Method URL
GET /v1/users/<USER_ID>/recommendations

 

Parameters

Param Required? Value Description
<USER_ID> Yes string The unique id of the user. This id should exactly match the id sent to the Behavioral API in association with the given user’s behavioral events.
start_index No integer If specified, the start_index parameter changes the response of the User Recommendations call to support infinite scroll. start_index dictates where in the list of recommendations to begin loading content. The response will include a specified number of items, in addition to a next_index upon which the following query is made. See below for an example response.
category No string The name of the category or categories by which you would like to filter recommendations. For example, if you’d like to return only items that are either “comedy” AND “kids”, OR “animation” AND “kids”, specify the category filter as category=comedy&kids|animation&kids. You must properly escape these special characters from the category parameter.
exclude_category No string A comma separated list of item categories that you would like to exclude from all results. For example, if you’d like to exclude content from either the “kids” or “fantasy” categories, specify the filter exclude_category=kids,fantasy. This parameter must be properly escaped.
type No string The specific type of recommendations to be returned. The types available are the unique types associated with your items (e.g. movie, series, article, apparel, subscription, etc). You may specify multiple types using a comma separator like the following: type=movie,series.
limit No integer The number of results to return. Default limit is 10. The maximum number of results that can be returned is 50 if no category is specified, and 20 if a category if specified.
payment_type No string The content or item payment type by which you would like to filter. You may specify multiple payment types as a comma separated string like the following: payment_type=rental,purchase. Valid values are: free, rental, purchase, or subscription.
exclude_items No string A comma separated list of item ids that you would like to exclude from results. For example, to filter out item ID “a” and item ID “b”, you’d specify it as follows: exclude_items=a,b
available_since No integer The maximum number of seconds ago that items can be available. For example, to restrict to items that are less than 24 hours old, you’d specify available_since=86400.
expires_in No integer The maximum number of seconds from now that items can be available before they expire. For example, to restrict to items that are only available for the next 24 hours, you’d specify expires_in=86400.
publishers No string For businesses with multiple properties or brands, you may filter items by their original publisher or creator. For example, if there are items that belong to publisher1, publisher2, and publisher3, you may filter the response to just publisher1 and publisher2 by specifying the publishers filter as publishers=publisher1&publisher2. This parameter must be properly escaped.

 

Example Request (without pagination for infinite scroll)

http://api.vidora.com/v1/users/<USER_ID>/recommendations?api_key=<YOUR_KEY>&category=comedy&limit=3&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response (without pagination for infinite scroll)

{
  "items": [
    { "id": "1" },
    { "id": "2" },
    { "id": "3" }
  ]
}

The above example request makes a signed call to User Recommendations to retrieve the top 3 recommended items for user <USER_ID>, filtered by category “comedy”. The response includes 3 items with ids “1”, “2”, and “3”.

Example Request (with pagination for infinite scroll)

http://api.vidora.com/v1/users/<USER_ID>/recommendations?api_key=<YOUR_KEY>&start_index=0&limit=3&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response (with pagination for infinite scroll)

{
  "items": [
    { "id": "1" },
    { "id": "2" },
    { "id": "3" }
  ],
  "limit": 3,
  "start_index": 0,
  "next_index": 3
}

The above example request makes a signed call to User Recommendations to retrieve the top 3 recommended items to include in an infinite scroll experience for user <USER_ID>. The response includes 3 items with ids “1”, “2”, and “3”. The response also includes a next_index of 3, indicating that when user <USER_ID> scrolls to the third item, another call should be made with a start_index of 3 to return recommended items 4-6.

When paginating, next_index specifies the value to be used as the start_index in the subsequent API call. When next_index returns null, the end of the paginated list has been reached. Note that there is no guarantee that items will be unique across API calls. If the list of recommended content is regenerated in the span of time between pagination calls, items that have shifted down in the content list may reappear in subsequent calls.

Personalization Item Similarities

Returns the top similar item ids for the given user and item. As with User

Recommendations, the Personalized Item Similarities API call supports both standard and custom filtering.

You may test the number of items available to serve your request with the Test Your Personalization API Filters tool.

Request

Method URL
GET /v1/users/<USER_ID>/items/<ITEM_ID>/similars

 

Parameters

Param Required? Value Description
<USER_ID> Yes string The unique id of the user. This id should exactly match the id sent to the Behavioral API in association with the given user’s behavioral events.
<ITEM_ID> Yes string The id of the item you want to get similars for. This id should exactly match the id sent to Vidora in your content feed or catalog.
limit No integer The number of results to return. Default limit is 10. The maximum number of results that can be returned is 50.
category No string The name of the category or categories by which you would like to filter similars. For example, if you’d like to return only items that are either “comedy” AND “kids”, OR “animation” AND “kids”, specify the category filter as category=comedy&kids|animation&kids. You must properly escape these special characters from the category parameter.
exclude_category No string A comma separated list of item categories that you would like to exclude from all results. For example, if you’d like to exclude content from either the “kids” or “fantasy” categories, specify the filter exclude_category=kids,fantasy. This parameter must be properly escaped.
type No string The specific type of similars to be returned. The types available are the unique types associated with your items (e.g. movie, series, article, apparel, subscription, etc). You may specify multiple types using a comma separator like the following: type=movie,series.
payment_type No string The content or item payment type by which you would like to filter. You may specify multiple payment types as a comma separated string like the following: payment_type=rental,purchase. Valid values are: free, rental, purchase, or subscription.
available_since No integer The maximum number of seconds ago that items can be available. For example, to restrict to items that are less than 24 hours old, you’d specify available_since=86400.
expires_in No integer The maximum number of seconds from now that items can be available before they expire. For example, to restrict to items that are only available for the next 24 hours, you’d specify expires_in=86400.
publishers No string For businesses with multiple properties or brands, you may filter items by their original publisher or creator. For example, if there are items that belong to publisher1, publisher2, and publisher3, you may filter the response to just publisher1 and publisher2 by specifying the publishers filter as publishers=publisher1&publisher2. This parameter must be properly escaped.

 

Example Request

http://api.vidora.com/v1/users/<USER_ID>/items/<ITEM_ID>/similars?api_key=<YOUR_KEY>&limit=5&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

{ "items": ["2", "3", "4", "5", "6"] }

The above example request makes a signed call to Personalized Item Similarities to retrieve for user <USER_ID> the top 5 similar items to item <ITEM_ID>, filtered by custom “availability” parameter “soldout”. The response includes 5 items with ids “2”, “3”, “4”, “5”, and “6”.

Popularity

Returns a ranked list of the most popular items within your entire content library or catalog.

You may test the number of items available to serve your request with the Test Your Personalization API Filters tool.

Request

Method URL
GET /v1/items/popular

 

Parameters

Param Required? Value Description
page No integer Each page returns up to 1000 item ids. Default page number is 1.

 

Example Request

http://api.vidora.com/v1/items/popular?api_key=<YOUR_KEY>&expires=2018-01-01T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

{
  "page": 1,
  "num_pages": 10,
  "items": [
    { "id": "1", "rank": "1" },
    { "id": "2", "rank": "2" },
    { "id": "3", "rank": "3" }
  ]
}

The above example makes a signed call to Popularity to retrieve a ranked list of users likely to engage with item “abc”. The response for this call indicates that page 1 of users was returned, out of 10 pages available. Up to 1000 items are returned on this page (three shown, ranked 1-3 with ids “1”, “2”, and 3″ respectively).

Trending

Returns a ranked list of trending items in your content library or catalog based on recent activity. To compute the trending score of an item, Vidora takes the derivative of its CTR over the last “k” hours, where “k” changes over time within the range of 48-72 hours. To account for outliers, the item must also have a minimum number of clicks.

You may test the number of items available to serve your request with the Test Your Personalization API Filters tool.

Request

Method URL
GET /v1/items/trending

 

Parameters

Param Required? Value Description
limit No integer Number of items to return. Default limit is 10.
categories No string The name of the category or categories by which you would like to filter popular items. For example, if you’d like to return only items that are either “comedy” AND “kids”, OR “animation” AND “kids”, specify the category filter as category=comedy&kids|animation&kids. You must properly escape these special characters from the category parameter.
exclude_category No string A comma separated list of item categories that you would like to exclude from all results. For example, if you’d like to exclude content from either the “kids” or “fantasy” categories, specify the filter exclude_category=kids,fantasy. This parameter must be properly escaped.
publishers No string For businesses with multiple properties or brands, you may filter items by their original publisher or creator. For example, if there are items that belong to publisher1, publisher2, and publisher3, you may filter the response to just publisher1 and publisher2 by specifying the publishers filter as publishers=publisher1&publisher2. This parameter must be properly escaped.

 

Example Request

http://api.vidora.com/v1/items/trending?api_key=<YOUR_KEY>&categories=womens%26accessories&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

["1", "2", "3"]

The above example makes a signed call to Trending to retrieve a ranked list of 3 trending items, filtered by items within category “womens” AND category “accessories”. The response includes 3 items with ids “1”, “2”, and “3”.

Recent Items

Returns ids of items that the given user has recently interacted with, ranked by recency of interaction.

Request

Method URL
GET /v1/users/<USER_ID>/recently_interacted

 

Parameters

Param Required? Value Description
<USER_ID> Yes string The unique id of the user. This id should exactly match the id sent to the Behavioral API in association with the given user’s behavioral events.
limit No integer The number of results to return. Default and maximum limit is 10. Maximum limit is 50.

 

Example Request

http://api.vidora.com/v1/users/<USER_ID>/recently_interacted?api_key=<YOUR_KEY>&limit=5&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

{ "items": ["1", "2", "3", "4", "5"] }

The above example makes a signed call to Recent Items to retrieve a ranked list of the 5 items that user <USER_ID> has most recently interacted with. The response includes 5 items with ids “1”, “2”, “3”, “4”, and “5”.

Next Episodes (video only)

Returns a set of series ids recently watched by a given user, along with the ids of the next episodes in each series. A maximum of 3 next episodes will be returned for each series id. For example, if the user has recently watched Glee Episode 2, then the result would contain an id for Glee episodes 3, 4, and 5.

Request

Method URL
GET /v1/users/<USER_ID>/next_episodes

 

Parameters

Param Required? Value Description
<USER_ID> Yes string The unique id of the user. This id should exactly match the id sent to the Behavioral API in association with the given user’s behavioral events.
limit No integer The number of results to return. Default and maximum limit is 10.

Example Request

http://api.vidora.com/v1/users/<USER_ID>/next_episodes?api_key=<YOUR_KEY>&limit=2&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

{
  "items": [
    { "id": "1", "episodes": ["10", "11", "12"] },     
    { "id": "2", "episodes": ["20", "21", "22"] },
    { "id": "3", "episodes": ["30"] }
  ]
}

The above example makes a signed call to Next Episodes to retrieve a list of the 2 series most recently watched by user <USER_ID>, as well as up-next episodes for the user for each of those series. The response includes 2 series with ids “1”, “2”. Episodes “10”, “11”, and “12” of series “1” are up next for user <USER_ID>. Episodes “20”, “21”, and “22” of series “2” are up next for the user.

Batch API

Vidora allows batching in order to process several API requests in a single HTTP request. Once all requests have been completed, the final composite response is returned.

Request

Method URL
POST /v1/batch

 

To make batched requests, a JSON object which describes the method and path for each individual API request should be sent in the body of the POST. Please note that the maximum number of requests that may be batched together is 20. If you are signing your Batch API request, please remember to include the POST body when generating the signature. It is not necessary to sign the individual API requests within the POST body.

Example Request

POST https://api.vidora.com/v1/batchj?api_key=<YOUR_KEY>&expires=2018-01-01T00%3A00&signature=<YOUR_SIGNATURE>

Content-Type: application/json
{
  "requests": [
    { "method": "GET", "path": "/v1/users/123/recommendations" },
    { "method": "GET", "path": "/v1/users/456/recommendations?&category=mens" }
  ]
}

Example Response

[
  {
    "status": 200,
    "response": {
      "items": [
        { "id": "1" },
        { "id": "2" },
        { "id": "3" }
      ]
    }
  },
  {
    "status": 404,
    "response": {
      "error": "Not found"
  }
]

The above example makes a signed call to Batch which makes two requests to User Recommendations: (1) retrieve the top recommended item for user “123”, and (2) retrieve the top recommended item for user “456”, filtered by category “mens”.

The response of the Batch API returns an array with results for each API call (in the same order as they were specified in the POST body). Note that the response of an individual API call included within a Batch request is the same response you would expect if you had called that API without using Batch. The response also includes a “status” parameter for each API call which refers to the HTTP status code for that call.

In the example response above, items “1”, “2”, and “3” are successfully returned for recommendation to user “123”. The call to retrieve recommendations for user “456” returns a “Not found” error, since user id “456” does not exist.

Possible HTTP status codes include:

Response Codes

Response Description
200 OK The request was successful.
400 Bad Request The request was invalid, possibly due to malformed parameters.
401 Unauthorized The api_key and/or signature was invalid.
404 Not Found The id used in the request was not found or the request URI does not exist.
500 Internal Error There was a server side error, and we cannot serve the request at the current time.

 

Working with Series and Episodes in the APIs

Vidora’s APIs work with any type of content or items. Most content stands alone by itself such as an article, video, or movie. However, content such as series and episodes have a parent-child relationship, and Vidora must set up rules for how the APIs will function depending on your business needs. For example, the Recommendations API call can be configured to return series or episodes. By default it is set up to return series.

Related Links

Still have questions? Reach out to support@vidora.com for more info!

Table of Contents