Appearance
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).
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;