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 catalog	See the table below for reference	Can 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:

Id	Title	Category	Price	InStock	SpecialOffer
1234	Black Check Knit Skirt	Clothing	19.00	Yes	Yes
3738	Gold Midi Pencil Skirt	Clothing	34.90	Yes	No
9737	Black Leather Women Bag	Accessories	24.90	No	Yes
1002	White Chain Zip Belt Bag	Accessories	14.90	Yes	No
6343	Leather-Look Leggings	Clothing	13.90	No	No
...	...	...	...	...	...

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

Operator	Meaning
=	Equal to
>	Greater than
<	Less than
>=	Greater than or equal to
<=	Less than or equal to
<>	Not equal to
LIKE	Matches 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 character	Description	Example
%	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.

Operator	Meaning
AND	TRUE if all evaluated expressions are TRUE
OR	TRUE if any of the evaluated expressions is TRUE
NOT	Reverses the value of any other operator

Arithmetic Operators

Operator	Meaning
+	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 name	Value
utc_timestamp	Current UTC unix timestamp (seconds)
signature	Hash 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).

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;