Pages

Recommendations require the Frosmo Recommendations add-on for the Frosmo Control Panel. To get the add-on, if you do not already have it, contact your Frosmo representative or sales@frosmo.com.

This guide shows you how to create and manage recommendations using the Graniitti API. This guide also describes the recommendation resource data model.

For instructions on how to develop recommendations with the Frosmo Platform, see the Frosmo Recommendations guide.

Introduction to the recommendation resource

The recommendation resource of the Graniitti API combines both a recommendation configuration and the recommendation data generated for that configuration:

  • When you retrieve a recommendation, the API returns both the configuration and the data.
  • When you create or update a recommendation, the API only creates or updates the configuration. The Frosmo Platform then separately generates the data and stores it for the recommendation.
  • When you delete a recommendation, the API deletes both the configuration and the data.

For actual recommendations displayed on a site, you retrieve the recommendation data with the Recommendations API.

You can also create, update, and delete recommendations in the Frosmo Control Panel. For more information, see Creating recommendations.

Working with recommendations

You can use the Graniitti API to:

The API provides the /sites/<site_id>/recommendations endpoint for working with recommendations. For complete information about the endpoint, see the Graniitti API reference.

Retrieving recommendations

Retrieving recommendations can take a long time if the recommendations contain huge amounts of recommendation data.

To retrieve all recommendations for a site, send a GET request to /sites/<site_id>/recommendations.

curl -X GET \
--header 'Authorization: Bearer <access_token>' \
'https://<graniitti_api_domain>/v0/sites/<site_id>/recommendations'

To retrieve a single recommendation for a site, send a GET request to /sites/<site_id>/recommendations/<recommendation_id>, where <recommendation_id> is the ID of the recommendation.

curl -X GET \
--header 'Authorization: Bearer <access_token>' \
'https://<graniitti_api_domain>/v0/sites/<site_id>/recommendations/<recommendation_id>'

If the request is successful, the API returns a JSON array of objects for GET /sites/<site_id>/recommendations and a JSON object for GET /sites/<site_id>/recommendations/<recommendation_id>. An object contains the configuration and data for a single recommendation, that is, the full data of a recommendation resource.

Creating recommendations

To create a new recommendation for a site, send a POST request to /sites/<site_id>/recommendations. Include the new recommendation configuration as a JSON object in the request body.

curl -X POST \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
-d '{<recommendation_configuration>}' \
'https://<graniitti_api_domain>/v0/sites/<site_id>/recommendations'

If the request is successful, the Frosmo Platform queues the recommendation for processing.

To track the generation progress, either retrieve the recommendation (optionally with the fields=status query parameter to minimize the response size) and check the status property in the returned JSON object, or check the recommendation status in the Frosmo Control Panel. For more information about the status, see Creating recommendations.

Here's an example of a recommendation configuration to pass in the POST request:

{
  "name": "Most viewed products",
  "description": "Top 10 most viewed products (24 h)",
  "type": "most_viewed",
  "status": "new",
  "frequency": "1h",
  "hours": 24,
  "limit": 10,
  "map_ids": "product",
  "params": [
    "type"
  ],
  "options": {
    "product_attrs": [
      "type"
    ]
  }
}

Updating recommendations

To update an existing recommendation for a site, send a PUT request to /sites/<site_id>/recommendations/<recommendation_id>, where <recommendation_id> is the ID of the recommendation. Include the updated recommendation configuration as a JSON object in the request body.

curl -X PUT \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
-d '{<recommendation_configuration>}' \
'https://<graniitti_api_domain>/v0/sites/<site_id>/recommendations/<recommendation_id>'

If the request is successful, the Frosmo Platform queues the recommendation for processing.

To track the generation progress, either retrieve the recommendation (optionally with the fields=status query parameter to minimize the response size) and check the status property in the returned JSON object, or check the recommendation status in the Frosmo Control Panel. For more information about the status, see Creating recommendations.

Here's an example of a recommendation configuration to pass in the PUT request:

{
  "name": "Most viewed products",
  "description": "Top 5 most viewed products (24 h)",
  "type": "most_viewed",
  "status": "new",
  "frequency": "1h",
  "hours": 24,
  "limit": 5,
  "map_ids": "product",
  "params": [
    "type"
  ],
  "options": {
    "product_attrs": [
      "type"
    ]
  }
}

Deleting recommendations

Deleting a recommendation deletes both the recommendation configuration and all associated recommendation data from the Frosmo back end. Any modification that uses the data will no longer have access to it.

To delete a recommendation for a site, send a DELETE request to /sites/<site_id>/recommendations/<recommendation_id>, where <recommendation_id> is the ID of the recommendation.

curl -X DELETE \
--header 'Authorization: Bearer <access_token>' \
'https://<graniitti_api_domain>/v0/sites/<site_id>/recommendations/<recommendation_id>'

If the request is successful, the Frosmo Platform deletes the recommendation.

Recommendation resource

This section describes the JSON object data model for a recommendation resource.

Recommendation object

The following table describes the main recommendation object.

Table: Recommendation object properties

PropertyDescriptionTypeRoleExample
id

Recommendation ID.

The Frosmo Platform sets this property. You cannot change it.

NumberRequired
"id": 1212
site_id

Site ID.

The Frosmo Platform sets this property. You cannot change it.

NumberRequired
"site_id": 2080
name

Recommendation name.

For users to easily distinguish between recommendations in the Frosmo Control Panel, it is recommended that you define a name that's unique within a site. The Frosmo Platform does not check the name for uniqueness.

StringRequired
"name": "Most viewed products"
descriptionDescription of what the recommendation is about.StringOptional
"description": "Top 10 most viewed products (24 h)"
type

Recommendation type.

The type defines the algorithm or filter that the Frosmo Platform uses to generate the recommendation data.

The possible values for the built-in types are:

  • bundle_converted
  • bundle_viewed
  • bundle_viewed_converted
  • most_converted
  • most_viewed

The default value is most_viewed.

For more information about the types, see Introduction to recommendations.

StringRequired
"type": "most_viewed"
status

Status of the recommendation data generation process.

The possible values are (in process order):

  • new: Recommendation generation has yet to be scheduled.
  • scheduled: Recommendation generation has been scheduled. Depending on how many other recommendations are queued for generation, it might take anywhere from a fraction of a second to several minutes before the generation starts.
  • started: Recommendation is being generated.
  • success: Recommendation was successfully generated.
  • failure: Recommendation generation failed.

The default value is new.

The Frosmo Platform sets this property. You cannot change it.

StringRequired
"status": "success"
duration

Total number of seconds it took to generate the recommendation data.

The Frosmo Platform sets this property. You cannot change it.

NumberOptional
"duration": 2
frequency

How often the recommendation data should be regenerated.

The possible values are:

  • 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 to another valid value).

The generation 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 was 1 day, the data would be next generated at 10:30 the following day.

It is recommended that you set frequency based on hours as follows:

HoursFrequency
Less than or equal to 24 (1 day)15m
25168 (1 – 7 days)1h
Greater than 168 (7 days)1d

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 time. You can check the time after the recommendation data has been generated at least once.

StringRequired
"frequency": "15m"
hours

Number of past hours of source data on which to base the recommendation.

For example, if you set this to 10, the recommendation will always be generated based on the last 10 hours of data collected from the site.

The maximum value is 336 (14 days).

The default value is 1.

NumberRequired
"hours": 24
limit

Maximum number of items, such as products, to include in the recommendation.

The default value is 100.

The value must be between 1 and 120.

NumberRequired
"limit": 10
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 (product ID, recommendation weight, and optional custom data) for each item. For more information, see Data point.

The default value is product.

StringOptional

Map each item ID to a product ID:

"map_ids": "product"

Do not map the item IDs:

"map_ids": ""
params

Names of the request parameters for filtering the recommendation data. If you also want to filter the recommendation data by segment, define a parameter for the segment ID as the last string in the array.

The parameters must be included in each Recommendations API request that retrieves this recommendation data.

You can filter recommendation data by any field or segment. How exactly you want to filter the data, and therefore what parameters to define for the request, is up to you. You can also freely name the parameters.

If you're using Recommendations API v2, you must define at least one parameter, as the API expects a request to include one or more parameters for filtering the recommendation data.

If you're using Recommendations API v1, do not use "name" as a parameter name, as the name property is reserved for defining the recommendation name in the API request.

The parameters together define a subset of recommended items whose data to return. In the request, you must define a value for each parameter, and the values must exactly equal the field or segment values (case insensitive) by which you want to filter the results. If you do not want to filter the returned data by a specific parameter, set its value to an empty string.

For example, if you're creating a product recommendation and want to return the recommendation data by product type, define a parameter name for type, such as type.

If the recommendation type is bundle_converted, bundle_viewed, or bundle_viewed_converted, define only the parameter for providing the ID of the product for which to generate the recommendation. Do not define any other parameters.

For product recommendations, the options.product_attrs array defines how the parameters map to fields in the product data from which the recommendation is generated.

The default value is ["type"].

Array of stringsOptional

Filter items by type:

"params": [
  "type"
]

Filter items by name, type, and price:

"params": [
  "name",
  "type",
  "price"
]

Filter items by type and visitor segment:

"params": [
  "type",
  "segment"
]
options

Configuration options specific to recommendation type.

The default value is {}.

For more information, see Options object.

ObjectRequiredFor examples, see Options object.
filters

Advanced product data filters for refining the set of recommended products to return.

While params define the product data fields and segments 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.

filters apply only to product data fields. If you want to filter recommendation results based on segments, use params.

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 evalute 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, either because the recommendation configuration does not define any params or because the request uses empty values for its params, the platform nonetheless applies the filters, if defined.

The default value is null.

For more information, see Filter object.

Array of filter objectsOptional

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 products 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.

StringOptional
"error": ""
created_at

Date and time when the recommendation configuration was created.

For more information about the data and time format, see Data formats.

The Frosmo Platform sets this property. You cannot change it.

StringRequired
"created_at": "2020-09-14T07:16:59+00:00"
updated_at

Date and time when the recommendation configuration was last updated.

For more information about the data and time format, see Data formats.

The Frosmo Platform sets this property. You cannot change it.

StringRequired
"updated_at": "2020-09-14T07:30:35+00:00"
model_updated_at

Date and time when the recommendation data was last generated.

For more information about the data and time format, see Data formats.

The Frosmo Platform sets this property. You cannot change it.

StringRequired
"model_updated_at": "2020-09-14T07:26:11+00:00"
model_version

Version of the data schema used by the Frosmo Platform to generate and structure the recommendation data.

The current and only supported version is 2.

The Frosmo Platform sets this property. You cannot change it.

NumberRequired
"model_version": 2

Options object

The following table describes the options child object of the main recommendation object. options contains the configuration options specific to recommendation type. If you have no options to define, set the value of options to an empty object ({}).

Table: Options object properties

PropertyDescriptionTypeRoleExample
basket_size

This property only applies when the recommendation type is bundle_converted, bundle_viewed, or bundle_viewed_converted.

Maximum number of viewed or purchased products to consider per visitor, starting with the first view or purchase within the time frame over which the recommendation is generated.

For example, if you set this to 10, and a visitor purchases 20 products within the time frame over which the recommendation is generated, the generation will only consider and potentially return the first 10 purchases when determining which products were purchased together.

The default value is 70.

NumberOptional
"basket_size": 20
category_delimiter

This property only applies when the recommendation type is most_converted or most_viewed.

Delimiter string by which to split the product type. If the string is empty, the product type is not split.

The default value is an empty string.

StringOptional
"category_delimiter": ""
product_attrs

Product data fields for filtering the generated recommendation data.

Define the field names that map to the request parameters defined in the params array. The mapping is done in order, so make sure you provide the field names in the same order as the matching parameter names in the params array.

To find out the available product data fields, use the Product API.

The field names are based on the product object properties of a Product API response.

To reference a property, whether a direct property of the product object, such as name, or a child property of the attributes object, such as price, simply use the property's name.

To reference within an array or object property of the attributes object, use dot or bracket notation (propertyName.nestedName) or index notation (propertyName[i]) as appropriate, depending on the nesting structure leading up to the target element or property.

You can also reference a property of the attributes object by using either dot notation (attributes.propertyName) or bracket notation (attributes['propertyName']), but this method is officially deprecated and will be phased out in the future.

The product_attrs array tells the Frosmo Platform how to map the parameters in the Recommendations API request to product data fields.

For example, if you've defined a request parameter for product type, define type as the product data field name to which the parameter maps.

If you define no request parameters, meaning you do not want to filter the recommendation data, leave this array empty.

The default value is [].

Array of stringsOptional

Map a lone request parameter to product type:

"product_attrs": [
  "type"
]

Map the first request parameter to product name, the second request parameter to product type, and the third request parameter to product price:

"product_attrs": [
  "name",
  "type",
  "price"
]

No request parameters to map to product data:

"product_attrs": []
segments

This property only applies when the recommendation type is most_converted or most_viewed.

IDs of the segments by which you want to allow the returned recommendation data to be filtered. You can use one of the IDs in a Recommendations API request (as the value of the segment parameter) to retrieve the recommendations only for that segment. If you do not define the ID of a given segment, you cannot filter the results by that segment.

If you define one or more segment IDs, the params array must include one parameter for the segment ID as its last item.

For example, if you define segment as the last item in the params array, and you define the segment IDs 123 and 456 in this property, you can use the parameter "segment": "123" or "segment": "456" in the Recommendations API request to filter the returned data by the corresponding segment.

The segment IDs are numerical strings, such as "123", without the sgmt_ prefix, which you see as part of segment IDs in the Frosmo Control Panel.

The default value is [].

Array of stringsOptional

Allow filtering by two segments:

"segments": [
  "123",
  "456"
]

Do not allow filtering by 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

PropertyDescriptionTypeRoleExample
nameFilter name.StringRequired
"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 evalute to true.

For more information, see Filter rule object.

Array of filter rule objectsRequired
"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 recommendation results.

Table: Filter rule object properties

PropertyDescriptionTypeRoleExample
attributeName of the product data field used for filtering products.StringRequired
"attribute": "type"
operator

Relational operator used to compare the value of the field defined in attribute to the value defined in value.

The comparison is case insensitive.

The platform supports the following operators:

  • =
  • !=
  • <
  • >
  • <=
  • >=
  • startsWith
  • endsWith
  • contains
  • in (value must be a JSON-stringified array)
  • notIn (value must be a JSON-stringified array)
  • regex

By default, the platform treats the product data field and value as strings. If the product data field is price or quantity, and if the operator is <, >, <=, or >=, the platform treats the product data field and value as numbers, not as strings, for comparison purposes.

For regular expressions (regex), use the RE2 syntax.

StringRequired
"operator": "!="
value

Value against which the value of the field defined in attribute is compared.

The value can be either a regular string or, if the operator is in or notIn, a JSON-stringified array.

StringRequired

Compare against a regular string:

"value": "Books"

Compare against a JSON-stringified array:

"value": "[\"Books\",\"Magazines\"]"

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 products from the category "Books"
"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 products from the category "Books", except ones from a specific company
"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 products 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: startsWith, endsWith, contains

Example: Return movies whose name starts with "A"
"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 books whose title ends with "for dummies" and that cost less than 30 currency
"filters": [{
    "name": "Include 'For Dummies' books",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Books"
    },{
        "attribute": "name",
        "operator": "endsWith",
        "value": "for dummies"
    }]
},{
    "name": "Include products 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
Example: Return products whose name contains "cheetah"
"filters": [{
    "name": "Include products 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

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 products 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: regex

The Frosmo Platform supports the RE2 syntax for regular expressions.

Example: Return movies whose name starts with "A" or "a" and ends in "s"
"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 object

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

{
  "id": 2030,
  "site_id": 2094,
  "name": "Most viewed products (only including dresses whose price is below 40.00)",
  "description": "Top 5 most viewed products in the past 14 days (336 hours)",
  "type": "most_viewed",
  "status": "success",
  "duration": 0,
  "frequency": "1d",
  "hours": 336,
  "limit": 5,
  "params": [
    "id",
    "name",
    "price"
  ],
  "map_ids": "product",
  "options": {
    "product_attrs": [
      "id",
      "name",
      "price"
    ]
  },
  "model": null,
  "error": "",
  "created_at": "2020-09-14T08:15:31+00:00",
  "updated_at": "2020-09-14T13:25:00+00:00",
  "model_updated_at": "2020-09-14T13:24:28+00:00",
  "model_version": 2,
  "filters": [
    {
      "name": "Include dresses that cost less than 40.00",
      "rules": [
        {
          "attribute": "name",
          "operator": "contains",
          "value": "Dress"
        },
        {
          "attribute": "price",
          "operator": "<",
          "value": "40.00"
        }
      ]
    }
  ]
}