How Can We Help?

Category Recommendations API

The Category Recommendations API provides low-latency access to recommendations made by a Recommendations pipeline that you’ve built in your Cortex account. The API returns up-to-date results which can be used to power personalized onsite experiences in your digital products.

Results from the Category Recommendations API differ from the Personalization 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. These item sets are referred to as “Categories” throughout the documentation.) 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.

The following section will describe how to enable and send GET requests to the Category Recommendations API. Note that you will need to authenticate each request unless this requirement has been disabled for your account. For clarity, the examples in this document assumes a Cortex account set up to make predictions about users. Note however that your account can be configured to predict for any type of entity tied to your event data (e.g. commerce inventory, media content, home listings, etc.).

Enabling the API

In order to use the Predictions API, you must first build a recurring Recommendations pipeline in Cortex. Once created, results from a Recommendations pipelines are automatically accessible through the Category Recommendations API. Note that if you create a Decision Project in Cortex using a Recommendations pipeline, its results may also be accessed directly from the client-side via the JavaScript Decision SDK.

Get User Recommendations

Given a unique entity ID (e.g. user_id) and a unique pipeline ID, returns up-to-date results generated by that pipeline for that entity. The response will include the full list of recommended categories (as an array of objects ranked in descending order of recommendation), up to a limit of 25. Each object in the response contains the following info:

  • Id: The unique name for the category being recommended
  • Score: Cortex’s predicted probability that this category will be the next one that the user interacts with

Each pipeline is identified by a unique ID that can be fetched using the Pipelines API or from Cortex.

Request

Method URL
GET /v1/entities/<ENTITY_ID>/pipelines/<PIPELINE_ID>/category_recommendations

Parameters

Param Required? Value Description
<ENTITY_ID> Yes string The unique ID of the entity (e.g. user) for which you’d like to return recommendations.
<PIPELINE_ID> Yes string The unique ID of the pipeline from which you’d like to return recommendations. A pipeline_id is only valid if it corresponds to a recurring Recommendations pipeline built in Cortex.

Example Request

http://api-us.vidora.com/v1/entities/<ENTITY_ID>/pipelines/<PIPELINE_ID>/category_recommendations?api_key=<YOUR_KEY>&expires=2020-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

[ 
    {"id": "sports", "score": 0.27396},
    {"id": "news", "score": 0.16438},
    {"id": "politics", "score": 0.13150},
    {"id": "entertainment", "score": 0.10520},
    {"id": "cooking", "score": 0.08416},
    {"id": "local", "score": 0.06733},    
    {"id": "national", "score": 0.06060},
    {"id": "opinion", "score": 0.03636},
    {"id": "world", "score": 0.02909},
    {"id": "business", "score": 0.02036},
    {"id": "technology", "score": 0.01425},
    {"id": "travel", "score": 0.01283}
]

The above example shows a GET request to return a ranked list of 12 recommended categories from pipeline <PIPELINE_ID> for user <ENTITY_ID>. The response indicates that the user’s top recommended category is “sports”, with a predicted 27.4% likelihood that “sports” will be the next category that the user interacts with.

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.

Rate Limits

To ensure maximum performance, please limit your Predictions API requests to no more than 800 requests per second.

Related Links

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

Table of Contents