How Can We Help?
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 products they love most. The Personalization API exposes unique recommendations generated by Cortex using event data submitted to the Behavioral API.
Results from the Personalization API differ from a Recommendations pipeline (which is served by the Category Recommendations API) in a few key ways. Recommendations pipelines are more flexible in that they can be used to recommend any set of items to your users (e.g. categories, topics, marketing channels, etc.). The Personalization API, on the other hand, is limited to content or product recommendations. However, the Personalization API generates recommendations which update in real-time, and comes equipped with robust systems for filtering results by metadata such as category, type, and others.
GET requests are made to Cortex’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, 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.
Note that you will need to authenticate each request unless this requirement has been disabled for your account.
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-us.vidora.com/v1/users/<USER_ID>/recommendations?api_key=<YOUR_KEY>&category=comedy%26drama%26action&limit=3&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>
API Methods
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. |
| excluded_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 excluded_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-us.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-us.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.
Personalized 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 Cortex 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. |
| excluded_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 excluded_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-us.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”.
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, Cortex 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 trending 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. |
| excluded_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 excluded_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-us.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”.
Other Notes
Rate Limits
To ensure maximum performance, please limit your Personalization API requests to no more than 800 requests per second.
Caching
In order to ensure fast response times (on the order of ~10-20ms), Cortex’s Personalization API pulls from a cache containing all the items which satisfy a particular set of API query parameters. The API takes these cached items, and personalizes them on a per-user basis. This cache is updated asynchronously whenever a request is made. If no request has been made in the last 24 hours, the cache is emptied to prevent stale items from being returned.
For example, say you are filtering your recommended items for recency by applying the query parameter available_since=9600. If it has been less than 24 hours since this request was last made, the API will return items that satisfied the recency filter at the time the cache was last updated. If this request has not been made in the past day, the cache will be empty and thus the response will not include any items until the next time the request is made.
If you are making frequent requests to the Personalization API with a constant set of query parameters, the cache will be continuously updated so that all requests return a proper set of items. However, note that if you are testing in a non-production environment or making infrequent requests (e.g. for recurring email campaigns), you may see empty responses and/or outdated items from time to time. In order to avoid this scenario, Cortex can set up a cache-warming process to regularly update the cache for a set of query parameters.
Batching API Requests
Cortex 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-us.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.
Response Codes
Possible HTTP status codes include:
| 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. |
Related Links
Still have questions? Reach out to support@mparticle.com for more info!