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.
Table: Recommendation configuration object properties
Property | Description | Type | Role | Example | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
id | Recommendation configuration ID. The platform sets this property. You cannot change it. | Number | Required | "id": 2030 | ||||||||
site_id | Site ID. 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 | 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:
The default value is 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):
The default value is The platform sets this property. If you use the Graniitti API to manually set this property to anything other than If you update the recommendation configuration with the Graniitti API and want to queue the configuration for immediate data generation, set this property to | String | Required | "status": "success" | ||||||||
duration | Total number of seconds it took to generate the recommendation data. 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:
The default value is 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:
It is recommended that you set
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 The minimum value is The default value is | Number | Required | "hours": 336 | ||||||||
limit | Maximum number of recommended items to return. The minimum value is The default value is | 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 Defining the parametersYou can filter the results by any data field. You can also filter the results by segment if the recommendation type is If the recommendation type is If the recommendation type is You can freely name the parameters. You must define at least one parameter. For product recommendations, the 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" ] Filter recommended items by category, price, and visitor segment: "params": [ "category", "price", "segment" ] | ||||||||
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:
If you're creating a product recommendation and want to return the full product data in the recommendation results, set this property to The default value is | 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 | This property is only valid for product recommendations. Advanced product data filters for refining the set of recommended products to return. While You can use 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 The default value is 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 '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" }] }] For more examples, see Filter examples. | ||||||||
model | 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. 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. 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. 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. 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 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.
Table: Options object properties
Property | Description | Type | Role | Example |
---|---|---|---|---|
category_delimiter | This property is only valid for product recommendations whose type is 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 The default value is an empty string ( | String | Optional | "category_delimiter": "/" |
min_weight | This property is only valid for recommendations whose type is Minimum data point weight for including the data point (item) in the recommendation results. For The default value is | Number | Optional | "min_weight": 10 |
product_attrs | 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 To find out the available product attributes, use the Product API. 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 If a child property of the The For example, if you've defined a request parameter for product category, define You must define at least one product attribute name (corresponding to the one minimum request parameter in | 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": [] |
segments | This property is only valid for recommendations whose type is IDs of the segments by which you want to allow the recommendation results to be filtered. You can use the IDs in Recommendations API requests (as the value of the segment parameter) to retrieve the recommendations only for a given segment. If you define one or more segment IDs, the If you do not define the ID of a given segment, you cannot filter the results by that segment. For example, if you define The segment IDs are numbers, such as The default value is | Array of numbers | Optional | Allow filtering by two segments: "segments": [ 123, 456 ] Do not allow filtering by any segment: "segments": [] |
Filter object
The following table describes the filter object of the filters
array. A filter defines a single rule set for filtering recommended products.
Table: 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.
Table: 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 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 The value can be either a regular string or, if the operator is For regular expressions ( If the operator is | 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.
The comparison is always case-insensitive.
Table: Supported filter rule operators
Operator | Description | Attribute type | Target type |
---|---|---|---|
= | The rule evaluates to 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 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 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 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 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 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 Example Rule: <type> contains "shoes" type: "Fashion/Shoes" -> TRUE type: "Fashion/Suits" -> FALSE | String | String |
notContains | The rule evaluates to Example Rule: <type> notContains "shoes" type: "Fashion/Shoes" -> FALSE type: "Fashion/Suits" -> TRUE | String | String |
startsWith | The rule evaluates to Example Rule: <type> startsWith "Fashion" type: "Fashion/Shoes" -> TRUE type: "Food/Seafood" -> FALSE | String | String |
startsWithAny | The rule evaluates to 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 Example Rule: <type> endsWith "Shoes" type: "Fashion/Shoes" -> TRUE type: "Food/Seafood" -> FALSE | String | String |
in | The rule evaluates to 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 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 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 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 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 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 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 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 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 The attribute must be one of the following datetime attributes:
The target value must be a duration string: a sequence of numbers followed by a unit suffix. The supported units are 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 | String | String |
notDuring | The rule evaluates to The attribute must be one of the following datetime attributes:
The target value must be a duration string: a sequence of numbers followed by a unit suffix. The supported units are 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 | String | String |
exists | The rule evaluates to 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 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 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 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: =, !=, >, <, >=, <=
Filter examples: contains, notContains, startsWith, startsWithAny, endsWith
Filter examples: in, notIn
Filter examples: arrayIncludes, arrayNotIncludes, arrayIncludesAny, arrayNotIncludesAny, anyElementContains, anyElementStartsWith, anyElementEndsWith
Filter examples: during, not during
Filter examples: exists, notExists
Filter examples: regex, notRegex
The platform supports the RE2 syntax for regular expressions.
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.
Table: 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.
Table: 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 |