Recommendation configuration reference

This reference describes the JSON object data model for a recommendation configuration. Use this reference when creating and editing recommendation configurations.

You create and manage recommendation configurations in the Frosmo Control Panel or with the Graniitti API.

Frosmo Control Panel vs. Graniitti API

The Frosmo Control Panel exposes only the crucial object properties, while the Graniitti API allows you to work with the full set of properties in the data model. It is recommended that you use the Control Panel by default. Use the Graniitti API only for troubleshooting or if you're creating your own application for accessing the Frosmo back end.

You can view and define the following properties in the Control Panel:

• name (required)

• description (optional)

• type (required)

• frequency (required)

• hours (required)

• limit (required)

• params (required)

• map_ids (optional)

• options (required)

• filters (optional)

Recommendation configuration object

The following table describes the main recommendation configuration object.

Recommendation configuration object properties

Property	Description	Type	Role	Example
id	Recommendation configuration ID. info The platform sets this property. You cannot change it.	Number	Required	"id": 2030
site_id	Site ID. info The platform sets this property. You cannot change it.	Number	Required	"site_id": 2094
name	Recommendation configuration name. The name must be unique within the site. The platform validates the name when saving the configuration and throws an error if the name is not unique. The default value is a randomly generated universally unique identifier (UUID). It is recommended that you change the name to something descriptive and useful for users.	String	Required	"name": "Most viewed affordable shirts"
description	Description of the recommendation configuration. Use the description to explain what sort of recommendation the configuration generates. The default value is Newly created recommendation.	String	Optional	"description": "Top 5 most viewed shirts in the past 14 days that cost less than 30.00"
type	Recommendation type. The type defines the algorithm that the platform uses to generate the recommendation. The possible values for the built-in algorithms are: bundle_converted bundle_viewed bundle_viewed_converted most_converted most_viewed The default value is most_viewed. For more information about the algorithms, see Supported recommendation algorithms.	String	Required	"type": "most_viewed"
status	Current status of recommendation data generation. The possible values are (in process order): new: Recommendation data generation has yet to be scheduled. scheduled: Recommendation data generation has been scheduled. Depending on how many other recommendation configurations are in the queue, it might take anywhere from a fraction of a second to several minutes before the data generation starts. started: Recommendation data is being generated. success: Recommendation data was successfully generated. failure: Recommendation data generation failed. The default value is new. info The platform sets this property. If you use the Graniitti API to manually set this property to anything other thannew, the change has no effect on the data generation. tip If you update the recommendation configuration with the Graniitti API and want to queue the configuration for immediate data generation, set this property to new.	String	Required	"status": "success"
duration	Total number of seconds it took to generate the recommendation data. note The platform sets this property. Do not set it manually.	Number	Optional	"duration": 1
frequency	How often the recommendation data is to be regenerated. The possible values are: 0m: Recommendation data is not automatically regenerated. You must manually generate the data. 15m: 15 minutes 1h: 1 hour 1d: 1 day (24 hours) The default value is 15m. If you enter a value not listed above and save the configuration, the platform ignores the value and retains the existing one (default value unless previously saved with another valid value). The regeneration point in time is calculated based on the last time the data was generated (either automatically or manually). For example: If the frequency is 15 minutes, and the data is generated at 10:15, the data is next generated at 10:30. If the frequency is 1 day, and the data is generated at 10:15, the data is next generated at 10:15 the following day. It is recommended that you set frequency based on hours as follows: Hours Frequency Less than or equal to 24 (1 day) 15m 25–168 (1–7 days) 1h Greater than 168 (7 days) 1d info If generating the recommendation data takes longer than the defined frequency, increase the frequency, as there's no point in having a frequency that's shorter than the actual generation duration. You can check the duration after the recommendation data has been generated at least once.	String	Required	"frequency": "1d"
hours	Amount of usage data on which to base the recommendation. The amount is in past hours of data counting from when the platform starts generating the recommendation. For example, if you set this to 10, the platform always generates the recommendation based on the last 10 hours of usage data collected from the site. The minimum value is 1. The maximum value is 1440 (60 days). The default value is 1.	Number	Required	"hours": 336
limit	Maximum number of recommended items to return. The minimum value is 1. The maximum value is 120. The default value is 20.	Number	Required	"limit": 5
params	Names for the Recommendations API request parameters for filtering the recommendation results. The parameters you define here determine the parameters that you can use in a request to filter which recommended items to return. For example, if you're creating a product recommendation and want to filter the results by product category and price, define the names for two parameters: one for category and the other for price, such as category and price. Defining the parameters You can filter the results by any data field. How exactly you want to filter the results, and therefore what parameters to define for the request, is up to you. If the recommendation type is bundle_converted, bundle_viewed, or bundle_viewed_converted, define only a single parameter: the target field against which the recommendation is generated. For example, if you want to recommend products purchased together with a product the visitor just added to their shopping cart, define a parameter for product ID, since the recommendation is based on a specific product. Do not define any other parameters. You can freely name the parameters. You must define at least one parameter. info For product recommendations, the options.product_attrs property defines how the parameters map to product attributes in the product data. For information about using the parameters in a request, see Recommendations API reference (configurations).	Array of strings	Required	Filter recommended items by category: "params": [ "category" ] Filter recommended items by category and brand: "params": [ "category", "brand" ]
map_ids	Logic for mapping the IDs of the recommended items to source data in the Frosmo back end. This determines what data the recommendation actually returns for each item. The possible values are: product: Map each item ID to a product ID. Return the full product data for each ID. Empty string: Do not map the item IDs to anything. Return the raw recommendation data (ID and recommendation weight) for each item. If you're creating a product recommendation and want to return the full product data in the recommendation results, set this property to product. The default value is product.	String	Optional	Map each item ID to a product ID: "map_ids": "product" Do not map the item IDs: "map_ids": ""
options	Configuration options specific to recommendation type. If you have no options to define, set this property to an empty object ({}). The default value is {}. For more information, see Options object.	Object	Required	For examples, see Options object.
filters	note This property is only valid for product recommendations. Advanced product data filters for refining the set of recommended products to return. While params define the fields that you can specify in a Recommendations API request to filter the results, filters define advanced result filtering that the platform applies automatically to all requests. note You can use filters only with product attributes. If you define multiple filters, the platform applies them all, that is, the platform treats the filters as combined with logical AND operators. The platform only returns items for whom all the filters evaluate to true. The platform automatically applies filters on top of the filtering performed with params. If a request does not perform any filtering with params, the platform nonetheless applies the filters, if defined. The default value is null. For more information, see Filter object.	Array of filter objects	Optional	Exclude books: "filters": [{ "name": "Exclude books", "rules": [{ "attribute": "type", "operator": "!=", "value": "Books" }] }] Only return books whose title ends with "for dummies" and that cost less than 30 (in the site currency): "filters": [{ "name": "Include &#39;For Dummies&#39; books", "rules": [{ "attribute": "type", "operator": "=", "value": "Books" },{ "attribute": "name", "operator": "endsWith", "value": "for dummies" }] },{ "name": "Include items that cost < 30", "rules": [{ "attribute": "price", "operator": "<", "value": "30" }] }] For more examples, see Filter examples.
model	note This is a deprecated property.
error	Error trace of what happened when the recommendation data generation failed. If the data generation was successful, the value is an empty string. note The platform sets this property. Do not set it manually.	String	Optional	"error": ""
created_at	Date and time when the recommendation configuration was created. For more information about the date and time format, see Graniitti API: Resources. info The platform sets this property. You cannot change it.	String	Required	"created_at": "2020-10-08T16:36:46+00:00"
updated_at	Date and time when the recommendation configuration was last updated. For more information about the date and time format, see Graniitti API: Resources. info The platform sets this property. You cannot change it.	String	Required	"updated_at": "2020-10-09T07:08:01+00:00"
model_updated_at	Date and time when the recommendation data was last generated. For more information about the date and time format, see Graniitti API: Resources. note The platform sets this property. Do not set it manually.	String	Required	"model_updated_at": "2020-10-09T07:07:42+00:00"
model_version	Version of the data schema used by the platform to generate and structure the recommendation data. The current and only supported version is 2. info The platform sets this property. You cannot change it.	Number	Required	"model_version": 2

Options object

The following table describes the options object. The object contains the configuration options specific to recommendation type.

Options object properties

Property	Description	Type	Role	Example
category_delimiter	note This property is only valid for product recommendations whose type is most_converted or most_viewed. Delimiter string by which to split the product category value. If the string is empty, the product category value is not split. If you define a delimiter, you must include type in product_attrs. The default value is an empty string ("").	String	Optional	"category_delimiter": "/"
min_weight	note This property is only valid for recommendations whose type is bundle_converted, bundle_viewed, or bundle_viewed_converted. Minimum data point weight for including the data point (item) in the recommendation results. For bundle product recommendations, a data point is a single recommended product, and the data point weight is the total number of times the product was purchased or viewed together with other products. The default value is 0, meaning all data points are returned.	Number	Optional	"min_weight": 10
product_attrs	note This property is only valid for product recommendations. Names of the product attributes by which to filter the recommendation results when using request parameters. Define the names of the product attributes that correspond to the request parameters defined in the params array. You must define a matching product attribute name for every parameter and in the order in which the parameters are defined in params. The names must match actual product attributes in the product data stored for your site. To find out the available product attributes, use the Product API. info The attribute names are based on the product object properties of a Product API response. To reference an attribute, whether a direct property of the product object, such as type, or a child property of the attributes object, such as price, simply use the corresponding property name, for example, type or price. If a child property of the attributes object is itself an array or object, you cannot reference its elements or properties. The product_attrs array tells the platform how to map the parameters in the Recommendations API request to product attributes in the product data stored for the site. For example, if you've defined a request parameter for product category, define type as the product attribute name to which the parameter maps, since type is the product attribute for product category or type. You must define at least one product attribute name (corresponding to the one minimum request parameter in params).	Array of strings	Required	One request parameter defined. Map the parameter to product category: "product_attrs": [ "type" ] Two request parameters defined. Map the first parameter to product category and the second parameter to product brand: "product_attrs": [ "type", "brand" ] No request parameters defined. Map nothing. "product_attrs": []

Filter object

The following table describes the filter object of the filters array. A filter defines a single rule set for filtering recommended products.

Filter object properties

Property	Description	Type	Role	Example
name	Filter name.	String	Required	"name": "Exclude books"
rules	One or more rules that together define the filtering logic for the filter. If you define multiple rules, the platform applies them all, that is, the platform treats the rules as combined with logical AND operators. The platform only returns products for whom all the rules evaluate to true. For more information, see Filter rule object.	Array of filter rule objects	Required	"rules": [{ "attribute": "type", "operator": "!=", "value": "Books" }]

Filter rule object

The following table describes the filter rule object of the rules array. A filter rule defines a single comparison operation that is used to include or exclude products from the recommendation results.

Filter rule object properties

Property	Description	Type	Role	Example
attribute	Name of the product attribute used for filtering products.	String	Required	"attribute": "type"
operator	Relational operator used to compare the value of the product attribute defined in attribute to the target value defined in value. The comparison is case-insensitive. By default, the platform treats the product attribute and the target value as strings. For more information about the supported operators, see Filter rule operators.	String	Required	"operator": "!="
value	Target value against which the value of the product attribute defined in attribute is compared. The value can be either a regular string or, if the operator is in, notIn, or startsWithAny, a JSON-stringified array of strings. For regular expressions (regex and notRegex operators), use the RE2 syntax. If the operator is exists or notExists, do not define a target value.	String	Required	Compare against a regular string: "value": "Books" Compare against a JSON-stringified array of strings: "value": "[\"Books\",\"Magazines\"]"

Filter rule operators

The following table describes the relational operators supported in filter rules. The Attribute type and Target type columns list the types of product attribute values and target values, respectively, that the operators support. For example, the = operator expects a Boolean, number, or string as the attribute value and a string as the target value.

note

The comparison is always case-insensitive.

Supported filter rule operators

Operator	Description	Attribute type	Target type
=	The rule evaluates to true if the attribute value equals the target value. Example Rule: <type> = "Fashion/Shoes" type: "Fashion/Shoes" -> TRUE type: "Fashion/Suits" -> FALSE The platform converts the attribute value to a string for the comparison.	Boolean Number String	String
!=	The rule evaluates to true if the attribute value does not equal the target value. Example Rule: <type> != "Fashion/Shoes" type: "Fashion/Shoes" -> FALSE type: "Fashion/Suits" -> TRUE The platform converts the attribute value to a string for the comparison.	Boolean Number String	String
>	The rule evaluates to true if the attribute value is greater than the target value. Example Rule: <price> > than 50 price: 40 -> FALSE price: 50 -> FALSE price: 60 -> TRUE If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.	Number String	String
<	The rule evaluates to true if the attribute value is less than the target value. Example Rule: <price> < 50 price: 40 -> TRUE price: 50 -> FALSE price: 60 -> FALSE If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.	Number String	String
>=	The rule evaluates to true if the attribute value is greater than or equal to the target value. Example Rule: <price> >= 50 price: 40 -> FALSE price: 50 -> TRUE price: 60 -> TRUE If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.	Number String	String
<=	The rule evaluates to true if the attribute value is less than or equal to the target value. Example Rule: <price> <= 50 price: 40 -> TRUE price: 50 -> TRUE price: 60 -> FALSE If the attribute is a number, the platform treats the attribute and the target value as numbers for the comparison.	Number String	String
contains	The rule evaluates to true if the attribute value contains or equals the target value. Example Rule: <type> contains "shoes" type: "Fashion/Shoes" -> TRUE type: "Fashion/Suits" -> FALSE	String	String
notContains	The rule evaluates to true if the attribute value does not contain or equal the target value. Example Rule: <type> notContains "shoes" type: "Fashion/Shoes" -> FALSE type: "Fashion/Suits" -> TRUE	String	String
startsWith	The rule evaluates to true if the attribute value begins with or equals the target value. Example Rule: <type> startsWith "Fashion" type: "Fashion/Shoes" -> TRUE type: "Food/Seafood" -> FALSE	String	String
startsWithAny	The rule evaluates to true if the attribute value begins with or equals any one of the target values. The target value must be a JSON-stringified array of strings. Example Rule: <type> startsWithAny "[\"Fashion\",\"Food\",\"Toys\"]" type: "Fashion/Shoes" -> TRUE type: "Food/Seafood" -> TRUE type: "Home/Bedroom" -> FALSE	String	Array of strings
endsWith	The rule evaluates to true if the attribute value ends with or equals the target value. Example Rule: <type> endsWith "Shoes" type: "Fashion/Shoes" -> TRUE type: "Food/Seafood" -> FALSE	String	String
in	The rule evaluates to true if the attribute value equals any one of the target values. The target value must be a JSON-stringified array of strings. Example Rule: <brand> in "[\"Cakita\",\"Kosch\",\"Wakita\"]" brand: "Cakita" -> TRUE brand: "Dawelt" -> FALSE brand: "Wakita" -> TRUE The platform converts the attribute value to a string for the comparison.	Boolean Number String	Array of strings
notIn	The rule evaluates to true if the attribute value equals none of the target values. The target value must be a JSON-stringified array of strings. Example Rule: <brand> notIn "[\"Cakita\",\"Kosch\",\"Wakita\"]" brand: "Cakita" -> FALSE brand: "Dawelt" -> TRUE brand: "Wakita" -> FALSE The platform converts the attribute value to a string for the comparison.	Boolean Number String	Array of strings
arrayIncludes	The rule evaluates to true if any one of the attribute values equals the target value. Example Rule: <features> arrayIncludes "respins" features: ["respins", "scatters", "wilds"] -> TRUE features: ["paylines", "scatters", "wilds"] -> FALSE The platform converts the attribute values to strings for the comparison. The platform expects the attribute values to be of the same type.	Array of numbers Array of strings	String
arrayNotIncludes	The rule evaluates to true if none of the attribute values equal the target value. Example Rule: <features> arrayNotIncludes "respins" features: ["respins", "scatters", "wilds"] -> FALSE features: ["paylines", "scatters", "wilds"] -> TRUE The platform converts the attribute values to strings for the comparison. The platform expects the attribute values to be of the same type.	Array of numbers Array of strings	String
arrayIncludesAny	The rule evaluates to true if at least one of the attribute values equals at least one of the target values. Example Rule: <features> arrayIncludesAny ["respins", "wilds"] features: ["respins", "scatters", "wilds"] -> TRUE features: ["free spins", "paylines", "scatters"] -> FALSE The platform converts the attribute values to strings for the comparison. The platform expects the attribute values to be of the same type.	Array of Booleans Array of numbers Array of strings	Array of Booleans Array of numbers Array of strings
arrayNotIncludesAny	The rule evaluates to true if none of the attribute values equals none of the target values. Example Rule: <features> arrayNotIncludesAny ["respins", "wilds"] features: ["respins", "scatters", "wilds"] -> FALSE features: ["free spins", "paylines", "scatters"] -> TRUE The platform converts the attribute values to strings for the comparison. The platform expects the attribute values to be of the same type.	Array of Booleans Array of numbers Array of strings	Array of Booleans Array of numbers Array of strings
anyElementContains	The rule evaluates to true if any one of the attribute values contains or equals the target value. Example Rule: <tags> anyElementContains "sale" tags: ["shirts", "short-sleeve", "top-rated"] -> FALSE tags: ["shirts", "long-sleeve", "summer sale"] -> TRUE tags: ["skirts", "sale 50%", "top-reviewed"] -> TRUE The platform converts the attribute values to strings for the comparison. The platform expects the attribute values to be of the same type.	Array of Booleans Array of numbers Array of strings	String
anyElementStartsWith	The rule evaluates to true if any one of the attribute values begins with or equals the target value. Example Rule: <tags> anyElementStartsWith "top" tags: ["shirts", "short-sleeve", "top-rated"] -> TRUE tags: ["shirts", "long-sleeve", "summer sale"] -> FALSE tags: ["skirts", "sale 50%", "top-reviewed"] -> TRUE The platform converts the attribute values to strings for the comparison. The platform expects the attribute values to be of the same type.	Array of Booleans Array of numbers Array of strings	String
anyElementEndsWith	The rule evaluates to true if any one of the attribute values ends with or equals the target value. Example Rule: <tags> anyElementEndsWith "sleeve" tags: ["shirts", "short-sleeve", "top-rated"] -> TRUE tags: ["shirts", "long-sleeve", "summer sale"] -> TRUE tags: ["skirts", "sale 50%", "top-reviewed"] -> FALSE The platform converts the attribute values to strings for the comparison. The platform expects the attribute values to be of the same type.	Array of Booleans Array of numbers Array of strings	String
during	The rule evaluates to true if the attribute value is inside the specified duration counting backwards from the current date and time of your Frosmo Platform instance. The attribute must be one of the following datetime attributes: created_at feed_updated_at updated_at Any string attribute that represents an ISO 8601 datetime value The target value must be a duration string: a sequence of numbers followed by a unit suffix. The supported units are h (hours) and d (days). For example: 24h or 7d. Example Rule: <created_at> during "10d" Current time: 2022-09-10 12:00:00 UTC+2 created_at: "2022-09-01T15:00:00+02:00" -> TRUE created_at: "2022-08-28T15:00:00+02:00" -> FALSE The platform subtracts the attribute value from the current date and time, and compares the result to the target value (duration). If the result is less than or equal to the target value, the operation evaluates to true. If the attribute value is a future datetime, the operation always evaluates to true. You therefore cannot filter out items whose datetime is in the future. Example: The current date and time is 2022-09-10 12:00:00, the attribute value is 2022-09-01 15:00:00, and the target value is 10d. Subtracting the attribute value from the current date and time yields 8d 21h. The result is less than the target value, the operation evaluates to true, and the item is therefore included in the recommendation results.	String	String
notDuring	The rule evaluates to true if the attribute value is not inside the specified duration counting backwards from the current date and time of your Frosmo Platform instance. The attribute must be one of the following datetime attributes: created_at feed_updated_at updated_at Any string attribute that represents an ISO 8601 datetime value The target value must be a duration string: a sequence of numbers followed by a unit suffix. The supported units are h (hours) and d (days). For example: 24h or 7d. Example Rule: <created_at> notDuring "10d" Current time: 2022-09-10 12:00:00 UTC+2 created_at: "2022-09-01T15:00:00+02:00" -> FALSE created_at: "2022-08-28T15:00:00+02:00" -> TRUE The platform subtracts the attribute value from the current date and time, and compares the result to the target value (duration). If the result is greater than the target value, the operation evaluates to true. Example: The current date and time is 2022-09-10 12:00:00, the attribute value is 2022-08-28 15:00:00, and the target value is 10d. Subtracting the attribute value from the current date and time yields 12d 21h. The result is greater than the target value, the operation evaluates to true, and the item is therefore included in the recommendation results.	String	String
exists	The rule evaluates to true if the attribute exists. The attribute exists if the platform has tracked at least one value for the attribute. Do not define a target value.	Array of Booleans Array of numbers Array of strings Boolean Number String	–
notExists	The rule evaluates to true if the attribute does not exist. The attribute does not exist if the platform has not tracked any values for the attribute. Do not define a target value.	Array of Booleans Array of numbers Array of strings Boolean Number String	–
regex	The rule evaluates to true if the attribute value matches the defined regular expression. Example Rule: <name> regex "^[Aa]\w+s$" name: "Aliens" -> TRUE name: "ALIENS" -> FALSE Define the regular expression using the RE2 syntax.	String	String
notRegex	The rule evaluates to true if the attribute value does not match the defined regular expression. Example Rule: <name> notRegex "^[Aa]\w+s$" name: "Aliens" -> FALSE name: "ALIENS" -> TRUE Define the regular expression using the RE2 syntax.	String	String

Filter examples

Here are some examples showing how to create filters with different operators and how those filters get evaluated.

Filter examples: =, !=, >, <, >=, <=

Example: Return all items from the category

"filters": [{
    "name": "Include books",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Books"
    }]
}]

// Evaluation examples:
// "type": "Books" -> TRUE
// "type": "BOOKS" -> TRUE
// "type": "books" -> TRUE
// "type": "Book" -> FALSE
// "type": "Magazines" -> FALSE

Example: Return all items from the category

"filters": [{
    "name": "Include books",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Books"
    }]
},{
    "name": "Exclude Vanity Press products",
    "rules": [{
        "attribute": "company",
        "operator": "!=",
        "value": "Vanity Press"
    }]
}]

// Evaluation examples:
// "type": "Books", "company": "Random House" -> TRUE
// "type": "Books", "company": "Vanity Press" -> FALSE
// "type": "Magazines", "company": "Random House" -> FALSE

Example: Return books that cost less than 30 currency

"filters": [{
    "name": "Include books",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Books"
    }]
},{
    "name": "Include items that cost < 30",
    "rules": [{
        "attribute": "price",
        "operator": "<",
        "value": "30"
    }]
}]

// Evaluation examples:
// "type": "Books", "price": "29.99" -> TRUE
// "type": "Books", "price": "39.99" -> FALSE
// "type": "Magazines", "price": "19.99" -> FALSE

Filter examples: contains, notContains, startsWith, startsWithAny, endsWith

Example: Return items whose name contains

"filters": [{
    "name": "Include items whose name contains 'cheetah'",
    "rules": [{
        "attribute": "name",
        "operator": "contains",
        "value": "cheetah"
    }]
}]

// Evaluation examples:
// "name": "Cheetah Plushy" -> TRUE
// "name": "Living with cheetahs, as told by a cheetah lover" -> TRUE
// "name": "Operation C.H.E.E.T.A.H." -> FALSE

Example: Return items whose name does not contain

"filters": [{
    "name": "Include items whose name does not contain 'cheetah'",
    "rules": [{
        "attribute": "name",
        "operator": "notContains",
        "value": "cheetah"
    }]
}]

// Evaluation examples:
// "name": "Cheetah Plushy" -> FALSE
// "name": "Living with cheetahs, as told by a cheetah lover" -> FALSE
// "name": "Operation C.H.E.E.T.A.H." -> TRUE

Example: Return movies whose name starts with

"filters": [{
    "name": "Include movies whose name starts with 'A'",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Movies"
    },{
        "attribute": "name",
        "operator": "startsWith",
        "value": "A"
    }]
}]

// Evaluation examples:
// "type": "Movies", "name": "Aliens" -> TRUE
// "type": "Movies", "name": "aliens" -> TRUE
// "type": "Movies", "name": "Tenet" -> FALSE
// "type": "Movie", "name": "Argo" -> FALSE

Example: Return movies whose name starts with

"filters": [{
    "name": "Include movies whose name starts with 'A', 'B', or 'C'",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Movies"
    },{
        "attribute": "name",
        "operator": "startsWithAny",
        "value": "[\"A\",\"B\",\"C\"]"
    }]
}]

// Evaluation examples:
// "type": "Movies", "name": "Aliens" -> TRUE
// "type": "Movies", "name": "aliens" -> TRUE
// "type": "Movies", "name": "Tenet" -> FALSE
// "type": "Movies", "name": "Babe" -> TRUE
// "type": "Movies", "name": "A Clockwork Orange" -> FALSE

Example: Return books whose title ends with

"filters": [{
    "name": "Include 'For Dummies' books",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Books"
    },{
        "attribute": "name",
        "operator": "endsWith",
        "value": "for dummies"
    }]
},{
    "name": "Include items that cost < 30",
    "rules": [{
        "attribute": "price",
        "operator": "<",
        "value": "30"
    }]
}]

// Evaluation examples:
// "type": "Books", "name": "JavaScript For Dummies", "price": "29.99" -> TRUE
// "type": "Books", "name": "Windows 10 For Dummies", "price": "39.99" -> FALSE
// "type": "Books", "name": "The Complete Idiot's Guide to JavaScript", "price": "19.99" -> FALSE

Filter examples: in, notIn

Example: Return hotels located in Cairo, Kochi, or La Paz

"filters": [{
    "name": "Include hotels",
    "rules": [{
        "attribute": "type",
        "operator": "in",
        "value": "[\"Hotel\",\"Hotels\"]"
    }]
},{
    "name": "Include items for Cairo, Kochi, and La Paz",
    "rules": [{
        "attribute": "city",
        "operator": "in",
        "value": "[\"Cairo\",\"Kochi\",\"La Paz\"]"
    }]
}]

// Evaluation examples:
// "type": "Hotel", "city": "Cairo" -> TRUE
// "type": "Hotels", "city": "Kochi" -> TRUE
// "type": "Hotels", "city": "LaPaz" -> FALSE

Example: Return beach volleyball events in Finland, except those in Tampere and Turku

"filters": [{
    "name": "Include Beach volleyball events",
    "rules": [{
        "attribute": "mainCategory",
        "operator": "in",
        "value": "[\"Beach Volleyball\",\"Volleyball, Beach\"]"
    }]
},{
    "name": "Include events for Finland",
    "rules": [{
        "attribute": "country",
        "operator": "=",
        "value": "Finland"
    }]
},{
    "name": "Exclude events for Tampere and Turku",
    "rules": [{
        "attribute": "city",
        "operator": "notIn",
        "value": "[\"Tampere\",\"Turku\"]"
    }]
}]

// Evaluation examples:
// "mainCategory": "Beach Volleyball", "country": "Finland", "city": "Helsinki" -> TRUE
// "mainCategory": "Beach Volleyball", "country": "Finland", "city": "Tampere" -> FALSE
// "mainCategory": "Volleyball, Beach", "country": "Finland", "city": "Turuku" -> TRUE

Filter examples: arrayIncludes, arrayNotIncludes, arrayIncludesAny, arrayNotIncludesAny, anyElementContains, anyElementStartsWith, anyElementEndsWith

Example: Return any item one whose categories is

"filters": [{
    "name": "Include slots",
    "rules": [{
        "attribute": "categories",
        "operator": "arrayIncludes",
        "value": "slots"
    }]
}]

// Evaluation examples:
// "categories": ["jackpot","slots"] -> TRUE
// "categories": ["jackpot","slot"] -> FALSE
// "categories": ["poker","stud"] -> FALSE

Example: Return any item one whose categories contains

"filters": [{
    "name": "Include items from categories whose name contains 'jack'",
    "rules": [{
        "attribute": "categories",
        "operator": "anyElementContains",
        "value": "jack"
    }]
}]

// Evaluation examples:
// "categories": ["jackpot","slots"] -> TRUE
// "categories": ["JACKPOT","slot"] -> TRUE
// "categories": ["blackjack","cards"] -> TRUE

Example: Return any item one whose categories starts with

"filters": [{
    "name": "Include items from categories whose name starts with 'slot'",
    "rules": [{
        "attribute": "categories",
        "operator": "anyElementStartsWith",
        "value": "slot"
    }]
}]

// Evaluation examples:
// "categories": ["jackpot","slots"] -> TRUE
// "categories": ["jackpot","slot"] -> TRUE
// "categories": ["poker","stud"] -> FALSE

Filter examples: during, not during

Example: Return items that have been created in the past 24 hours

"filters": [{
    "name": "Include new items (created in the past 24 hours)",
    "rules": [{
        "attribute": "created_at",
        "operator": "during",
        "value": "24h"
    }]
}]

// Evaluation examples when the current time is 2022-01-20 18:00:00 UTC+2:
// "created_at": "2022-01-20T13:23:03+02:00" -> TRUE
// "created_at": "2022-01-19T09:53:31+02:00" -> FALSE

Example: Return items that have not been updated in the past 30 days

"filters": [{
    "name": "Include old items (not updated in the past 30 days)",
    "rules": [{
        "attribute": "updated_at",
        "operator": "notDuring",
        "value": "30d"
    }]
}]

// Evaluation examples when the current time is 2022-01-20 18:00:00 UTC+2:
// "updated_at": "2021-11-11T00:03:54+02:00" -> TRUE
// "updated_at": "2022-01-20T14:52:16+02:00" -> FALSE

Filter examples: exists, notExists

Example: Return items without a name (either the name attribute is missing or the attribute has an empty value)

"filters": [{
    "name": "Include items without a name",
    "rules": [{
        "attribute": "name",
        "operator": "notExists"
    }]
}]

// Evaluation examples:
// ("name" attribute not found) -> TRUE
// "name": undefined -> TRUE
// "name": null -> TRUE
// "name": "" -> TRUE
// "name": "Aliens" -> FALSE

Filter examples: regex, notRegex

info

The platform supports the RE2 syntax for regular expressions.

Example: Return movies whose name starts with

"filters": [{
    "name": "Include movies whose name starts with 'A' or 'a' and ends in 's'",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Movies"
    },{
        "attribute": "name",
        "operator": "regex",
        "value": "^[Aa]\w+s$"
    }]
}]

// Evaluation examples:
// "type": "Movies", "name": "Aliens" -> TRUE
// "type": "Movies", "name": "aliens" -> TRUE
// "type": "Movies", "name": "ALIENS" -> FALSE
// "type": "Movies", "name": "Alien" -> FALSE

Example: Recommendation configuration object

The following is a full example of a recommendation object returned by the Graniitti API.

{
  "id": 2030,
  "site_id": 2094,
  "name": "Most viewed affordable shirts",
  "description": "Top 5 most viewed shirts in the past 14 days that cost less than 30.00",
  "type": "most_viewed",
  "status": "success",
  "duration": 1,
  "frequency": "1d",
  "hours": 336,
  "limit": 5,
  "params": [
    "category",
    "brand"
  ],
  "map_ids": "product",
  "options": {
    "product_attrs": [
      "type",
      "brand"
    ]
  },
  "model": null,
  "error": "",
  "created_at": "2020-09-14T08:15:31+00:00",
  "updated_at": "2020-10-08T15:45:59+00:00",
  "model_updated_at": "2020-10-08T15:45:48+00:00",
  "model_version": 2,
  "filters": [
    {
      "name": "Include shirts that cost less than 30.00",
      "rules": [
        {
          "attribute": "category",
          "operator": "contains",
          "value": "shirt"
        },
        {
          "attribute": "price",
          "operator": "<",
          "value": "30.00"
        }
      ]
    }
  ]
}

Supported recommendation algorithms

The following table describes the built-in recommendation algorithms that you can use in a recommendation configuration.

Supported recommendation algorithms

Name	Type	Description
Most purchased products	most_converted	Products that have been purchased the most.
Most viewed products	most_viewed	Products that have received the most views.
Products purchased together	bundle_converted	Visitors who purchased product A also purchased products B, C, and so on.
Products viewed together	bundle_viewed	Visitors who viewed product A also viewed products B, C, and so on.
Products viewed and purchased together	bundle_viewed_converted	Visitors who viewed and purchased product A also viewed and purchased products B, C, and so on.

While you can, in principle, use Frosmo Recommendations to generate recommendations from any data and using any recommendation algorithm, the system currently provides built-in support only for product recommendations based on the algorithms listed above. If you want to create other types of recommendations, contact Frosmo support.

Recommendation algorithms and the data layer

Recommendations rely on usage data collected from the site. The preferred way of collecting this data is through the data layer. The following table shows you what data each supported recommendation type uses for generating recommendations and which data layer object you can use to collect this data from the site.

Mapping recommendation types to data layer objects

Recommendation type	Source usage data	Data layer object
Most purchased products	Transaction	Transaction
Most viewed products	Product data	Product
Products purchased together	Transaction	Transaction
Products viewed together	Product data	Product
Products viewed and purchased together	Product data Transaction	Product Transaction