Skip to content

Recommender System

Overview

LYNX's prediction engine provides valuable recommendations that react in realtime to your customer's shopping journey, leveraging both customer behaviour and product details.

Filtering

When recommending items to a user, LYNX's AI prediction engine selects the most relevant ones to the user. However, it may be your policy to not recommend certain items. To narrow down the scope of the recommendable items, you can use the filter parameter when invoking the recommendations API methods.

Filter

A filter is an expression that allows you to filter the recommended items based on the values of their attributes. The attributes on which you can filter are the fields in your catalog. A filter expression defines the condition to be met for the items to be returned, and it's a combination of one or more predicates tied together by logical operators (AND, OR, and NOT). A predicate is an expression that returns TRUE or FALSE.

Predicates

A predicate has the following form:

p: [attribute] [comparison operator] [value]

[attribute][comparison operator][value]
The name of a field in your catalogSee the table below for referenceCan be a string, a number, or a boolean value. String values must be enclosed in single quotes (e.g.'string_value')

Examples

p1: Price > 15

p2: Category = 'Clothing'

p3: InStock = 'Yes'

Since a filter expression is a combination of one or more predicates tied together by logical operators, the following are valid filtering expressions:

Price > 15 (p1)

Price > 15 AND Category = 'Clothing' (p1 AND p2)

Price > 15 AND Category = 'Clothing' AND InStock = 'Yes' (p1 AND p2 AND p3)

Remarks

The order of precedence for the logical operators is NOT (highest), followed by AND, followed by OR. You can use parentheses to override this precedence in a filter expression.

(Price > 15 OR Category = 'Clothing) AND InStock = 'Yes' ((p1 OR p2) AND p3)

Examples

Consider the following sample catalog:

IdTitleCategoryPriceInStockSpecialOffer
1234Black Check Knit SkirtClothing19.00YesYes
3738Gold Midi Pencil SkirtClothing34.90YesNo
9737Black Leather Women BagAccessories24.90NoYes
1002White Chain Zip Belt BagAccessories14.90YesNo
6343Leather-Look LeggingsClothing13.90NoNo
..................

Example 1

Suppose USER_A has purchased ITEM_123. You may want to recommend to USER_A other items that are frequently bought together with ITEM_123. However, it may be your policy to recommend only items that are in stock. To do so, you should use the following simple filtering expression:

InStock='Yes'

The resulting API call should look like this:

https://ai.kickdynamic.cloud/api/v1/recommender/YOUR_MERCHANT_ID/items/ITEM_123
/bought-together?userId=USER_A&topK=10
&attributes=Title,Category,Price
&filter=InStock='Yes'

Example 2

Suppose USER_A has purchased ITEM_123. You may want to recommend to USER_A other items that are frequently bought together with ITEM_123. You may want to recommend only items that are in stock, that belong to the Clothing category, and that are on special offer. To do so, you should use the following filtering expression:

(InStock='Yes' AND Category='Clothing' AND SpecialOffer='Yes')

The resulting API call should look like this:

https://ai.kickdynamic.cloud/api/v1/recommender/YOUR_MERCHANT_ID/items/ITEM_123
/bought-together?userId=USER_A&topK=10
&attributes=Title,Category,Price
&filter=(InStock='Yes' AND Category='Clothing' AND Promotion='Yes')

Example 3

Suppose you want to recommend the most popular items in a specific category, but you also want the recommended items to have a price of at least 15.00 £ (in other words, you want the price to be equal to or greater than 15.00 £). To achieve your goal, you can use the following filtering expression:

(Price >= 15.00)

The resulting API call should look like this:

https://ai.kickdynamic.cloud/api/v1/recommender/YOUR_MERCHANT_ID/items/top-in-category
&attributes=Title,Category,Price
&filter=(Price >= 15.00)

Filtering Operators

Comparison Operators

OperatorMeaning
=Equal to
>Greater than
<Less than
>=Greater than or equal to
<=Less than or equal to
<>Not equal to
LIKEMatches a specified pattern

The LIKE comparison operator

The LIKE operator determines whether a text field in the catalog matches a specified pattern. A pattern can include regular characters and wildcard characters. Regular characters must match exactly the characters in the specified field, while wildcard characters can match arbitrary fragments of the specified field.

field [ NOT ] LIKE pattern

field is any valid text field in the catalog.

pattern is the specific string of characters to search for in field and can include the following wildcard character.

Wildcard characterDescriptionExample
%Any string of zero or more characters**description LIKE '%dress%'** finds all items with the word 'dress' anywhere in the item's description

Remarks

When you do string comparisons using the LIKE operator, all characters in the pattern string are significant, including any leading or trailing spaces.

Logical Operators

Logical operators are used to combine predicates to build more complex filtering expressions.

OperatorMeaning
ANDTRUE if all evaluated expressions are TRUE
ORTRUE if any of the evaluated expressions is TRUE
NOTReverses the value of any other operator

Arithmetic Operators

OperatorMeaning
+Add
-Subtract
*Multiply
/Divide
%Modulus

Authentication

HMAC-SHA256

HMAC-based authentication is the way you authenticate to LYNX's API. To be able to use HMAC-based authentication, you will need an api-key that needs to remain secret and known only to you and LYNX.

When making an API call to LYNX's Recommendation API you need to add the following parameters to every call:

Parameter nameValue
utc_timestampCurrent UTC unix timestamp (seconds)
signatureHash signature computed from your request URI path without protocol, host, and query string

How to sign a request

Let's see how to compute the signature for making valid recommendation API requests. For example if your api-key is api-key123456 and you want to make a call to the following URI:

https://lynx.kickdynamic.cloud/api/v1/recommender/1234567890/items/
445/bought/together?userId=ABCDEF&topK=10

First you need to take the URI's path without the protocol, host, and query string, as shown below:

/api/v1/recommender/1234567890/items/445/bought-together

Then you must append the utc_timestamp (UTC UNIX timestamp).

/api/v1/recommender/1234567890/items/445/bought-together?utc_timestamp=1565533332

Next you take the string above and generate a hash signature using the HMAC-SHA256 algorithm and the api-key which produces the following hash code (signature).

be450e6e1f99746f95ca8649f7b2f3d98f2f01c13418a1ab466b2006e2215b0a

Finally you append then utc_timestamp and the signature parameters to the API call as shown below.

https://lynx.kickdynamic.cloud/api/v1/recommender/1234567890/items/
445/bought-together?userId=ABCDEF&topK=10&utc_timestamp=1565533332
&signature=be450e6e1f99746f95ca8649f7b2f3d98f2f01c13418a1ab466b2006e2215b0a

Client-side implementation example

Here is an example of how to build a proper recommendation API request, implemented in a popular programming language.

C#

A C# example using .NET Framework 4.6 (or higher) or .NET Core 2.0 (or higher).

c#
string apikey = "api-key123456";
string uriToCall = "https://lynx.kickdynamic.cloud/api/v1/recommender/1234567890/items/445/bought/together?userId=ABCDEF&topK=10"
string uriToHash = "/api/v1/recommender/1234567890/items/445/bought/together";
long utc_timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds(); 
uriToHash = uriToHash + "?utc_timestamp=" + Convert.ToString(utc_timestamp);
HMACSHA256 hmac = new HMACSHA256(apiKey);
byte[] hashedText = hmac.ComputeHash(Encoding.ASCII.GetBytes(textToHash));
string signature = Convert.ToString(hashedText);
uriToCall = uriToCall + "&utc_timestamp=" + utc_timestamp + "&signature=" + signature;