Use the API to provide personalized recommendations to your users. The base URL for all requests is https://recommend.kontent.ai/.

To work with the Smart Recommendations API, send your requests over HTTPS and authenticate using the Authorization header in the following format: Authorization: Bearer <YOUR_API_KEY>.

To get your API key for the Smart RecommendAPI ations API, go to Kentico Kontent > Smart Recommendations > Smart Recommendations API key. The API key provide access to a single Kentico Kontent project. You will need different API keys for each of your projects.

We offer a .NET SDK and JavaScript SDK to easily use the Smart Recommendations API. However, no SDK is required to use the API.

Kentico Kontent returns standard HTTP status codes to indicate the success or failure of a request. In general, status codes in the 2xx range indicate a successful request, status codes in the 4xx range indicate errors caused by an incorrect input (for example, providing incorrect API key), and status codes in the 5xx range indicate an error on our side.

For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.

If you cannot identify and resolve an issue with your API call, you can contact us with the response status and the request ID you get in the error response.

Aside from giving Smart Recommendations enough data (through tracking) to build an accurate recommendations model, you can influence what recommendations you get. You can use three methods to modify the recommendation process.

1. Filtering – Lets you filter your content items by their taxonomy or multiple choice elements. In the recommendation database, these elements are converted to a set of properties you can use for filtering. For example, you can filter items tagged with the developer persona. Tip: You can find the properties in the Smart Recommendations UI under Content types to recommend.
2. Boosting – Lets you boost certain content items to make them more prominent and more likely to be recommended. For example, you can boost items updated in the last week or month.
3. Scenario selection – Lets you choose the scenario used for sorting the recommendations. The API recognizes the following scenarios:
   • Similar – the engine recommends content most similar to what the user is viewing at the moment.
   • Popular – the engine sorts the recommendations by popularity.
   • Default – the engine combines the scenarios above and sorts recommendations by similarity and popularity.

You can use these methods together to tune the recommendations you get. Both filtering and boosting rely on the Recombee query language (ReQL). To create correct queries, make sure you're familiar with the properties you can use within the recommendation database.

The Smart Recommendations API exposes several properties of the content items it indexes. This content structure can be used to create custom filters and boosters for your recommendations.

Structure of items in recommendation database

For example, to filter content tagged with the developer persona, use a ReQL filter query such as \"persona=developer\" in 'properties'.

You need to escape the ReQL queries correctly. You can combine different filters and use standard AND, OR, and NOT operators. See ReQL documentation for more information.

For example, to favor content updated within the last 30 days, use a ReQL booster query such as if 'lastupdated' >= now() - 259200000 then 2 else 1. This query makes it twice as likely to recommend items updated in the last 30 days (converted to milliseconds).

You can recommend content to your visitors using two approaches:

1. Recommend based on the content item they are viewing right now. This approach also supports filtering and boosting.
2. Recommend based on a search phrase.

In both cases, you need to assign a unique identifier (called visitId) to each visitor for Smart Recommendations to work correctly.

To take your visitors' location into account, go to Smart Recommendations in Kontent and activate Geolocation. Then, with each recommendation request, include the visitor's IP address.

The API sends the IP address to the IP Geolocation API service and saves the location it gets. The IP address is not stored nor used for any other purpose.

C#
// Specifies geolocation information about a visitor
var visitor = new VisitorDetails {
    // If you enabled Geolocation, provide the visitor's IP address
    Ip = "192.166.12.4",
    Referer = "google.com",
    // If you disabled Geolocation, you can specify location yourself
    Location = new LocationDetails {
        City = "Brno",
        Country = "Czech Republic",
        Timezone = "CET"
    }
};

You can also get the visitors' location on your own and send the location to the Smart Recommendation API in your own format.

To manually track visits, conversions, or partial content views, go to Kentico Kontent > Smart Recommendations and enable Manual tracking.

Make sure you do this after you've adjusted your app because this action disables automatic content visit tracking. With manual tracking is enabled, content visits are no longer tracked automatically.