For an introduction to retrieving recommendation data generated from recommendation strategies, see Retrieving recommendation data for strategies.
Learn how to make Recommendations API requests to retrieve recommendation data for strategies:
You can also retrieve recommendation data for strategies using the frosmo.easy.strategies.fetch() JavaScript function. The function supports all algorithms. For more information, see Retrieving recommendation data for strategies.
If you want to retrieve recommendation data generated from recommendation configurations, see Recommendations API reference (configurations).
Requests
URL
The URL for Recommendations API requests is https://<platform_instance>/recoApi/v2, where <platform_instance> is the domain name of your Frosmo Platform instance.
To get the URL for your Frosmo Platform instance:
- Log in to the Frosmo Control Panel, and select your site.
- In the header, click your username, and select API Access.
In the Recommendations API section, copy the URL.
Authentication
The Recommendations API does not require authentication.
Methods
The Recommendations API supports the GET HTTP method for recommendation strategies.
Syntax
To retrieve recommendation data for a recommendation strategy, make the following GET request:
GET https://<platform_instance>/recoApi/v2?method=strategy&
origin=<site_origin>&
strategy=<strategy_id>&
context={<strategy_context>}
Parameters
Table: Query parameters for Recommendations API requests (strategies)
| Parameter | Description | Type | Role | Example |
|---|---|---|---|---|
method | Request type. Use the value | String | Required | method=strategy |
origin | Site origin. To find out your site's origin, see Getting your site origin. | String | Required | origin=shop_company_com |
strategy | Recommendation strategy ID. | String | Required | strategy=product-page--recommended-for-you |
cookieId | Local Frosmo ID of the visitor who sees the recommendation returned by the API request. This parameter is required in the following cases:
The strategy requires a user context if it uses any of the following algorithms:
The ID allows the platform to use the visitor's user context and affinity profile for personalizing the recommendation for the visitor. This parameter has no effect if the strategy does not require a user context and is not set to apply affinity (either by the strategy itself or by | String | Optional | cookieId=dsr77t.kstzihlx |
context | Contextual information about the page where the API request is made. The information allows the API to return the correct recommendation data for the page. The exact information required depends on the page type of the recommendation strategy: the information must match the page type. The value is a JSON object. | Recommendation strategy context object | Required | # Product page context
context={
"page": {
"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
}
}
|
variants | Define whether to also return the data for product variants. If a product has one or more variants, the API returns the full product data for each variant in the The possible values are:
The default value is | Boolean | Optional | variants=true |
affinityPercentage | Level of visitor affinity (in percentages) applied to the recommendation. The higher the level, the more personalized the set of recommended items is for each individual visitor. The minimum value is If defined, this parameter overrides the level of affinity set in the strategy. This parameter has no effect unless | Number | Optional | affinityPercentage=50 |
profile | Define the visitor's profiling choice if the site uses selective profiling. The choice determines whether the API returns recommendation data that is personalized for the visitor. The possible values are:
The default value is empty. Each visitor's profiling choice is stored in their context. You can get the choice using the You must always define this parameter on a site that uses selective profiling. Never define this parameter on a site that does not use selective profiling. How the profiling choice worksIf you set the value to If you set the value to
Depending on the strategy settings, the API therefore either returns a non-personalized version of the recommendation or a recommendation with the personalized results removed. | String | Optional | profile=opt-out |
shuffle | Define whether to randomly shuffle the order of items in the recommendation data. By default, the items are in descending order of rank, with the most recommended item (as defined by the recommendation strategy) ranked highest. The possible values are:
The default value is If any affinity is applied, shuffling is disabled, irrespective of the value of this parameter. Affinity is applied when | Boolean | Optional | shuffle=true |
debug | Define whether to return debugging information about the recommendation data. Use the debugging information only for development and testing purposes. Do not use the information in production, since Frosmo does not guarantee that the information structure and content will remain the same. The debugging information for a recommendation consists of:
The possible values are:
The default value is | Boolean | Optional | debug=true |
Recommendation strategy context object
The following table describes the context object for recommendation strategies. The object provides information about the context into which the recommendation data is retrieved.
Table: Recommendation strategy context object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
page | Context information about the current page. | Page context object | Required | # Page context object for a product page
"page": {
"product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
}
|
Page context object
The following table describes the page object of the recommendation strategy context object. The page object provides context information about the current page.
The page context must match the page type of the recommendation strategy.
Table: Page context object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
cart | Context information about the current shopping cart page. | Cart page context object | Optional | "cart": {
"ids": [
"958",
"175",
"280"
]
}
|
category | Context information about the current category page. | Category page context object | Optional | "category": {
"name": "Books/Fiction/Fantasy",
"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative"
]
}
|
product | Context information about the current product page. Here, "product" refers to any item that a site sells or offers to visitors, or that the site otherwise tracks for conversions or transactions. A product can be, for example, a retail product, a blog article, an online game, a magazine subscription, or a downloadable brochure. | Product page context object | Optional | "product": {
"id": "719",
"category": "Books/Fiction/Fantasy"
}
|
search | Context information about the current search page. | Search page context object | Optional | "search": {
"ids": [
"958",
"655",
"358",
"809",
"955"
],
"categories": [
"Books/Fiction/Fantasy",
"Books/Fiction/Speculative"
"Books/Fiction/Scifi"
]
}
|
Cart page context object
The following table describes the cart object of the page context object. The cart object provides context information about the current shopping cart page.
Table: Cart page context object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
ids | IDs of the items currently in the visitor's shopping cart. You can define a maximum of 20 IDs. You must define at least one ID. The IDs are relevant for strategies that use the Bought together with items in the cart algorithm. The IDs are the target items against which the platform generates the recommendation. The platform matches the IDs against the You're free to choose the logic by which you select the IDs, especially if a visitor's shopping cart contains more than 20 items. | Array of strings | Required | "ids": [ "357", "958", "990" ] |
Category page context object
The following table describes the category object of the page context object. The category object provides context information about the current category page.
Table: Category page context object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
categories | Names of the categories whose items are shown on the current category page. The category names are relevant for strategies that use the Bought together with current category or Viewed together with current category algorithm, or that have the Only return items filter option selected. The platform generates the recommendation against the listed categories. The platform matches the category names against the You can also use partial category names, since the API checks whether the category names in the database start with the strings you provide here. For example:
Examples
| Array of strings | Required | "categories": [ "Books/Fiction/Fantasy", "Books/Fiction/Speculative", "Books/Kids/Fiction" ] |
Product page context object
The following table describes the product object of the page context object. The product object provides context information about the current product page.
Table: Product page context object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
id | Item ID. The ID is relevant for strategies that use the Bought together with current item or Viewed together with current item algorithm. The ID is the current item against which the platform generates the recommendation. The platform matches the ID against the | String | Required | "id": "719" |
category | Name of the category to which the item belongs. The category name is relevant for strategies that have the Only return items filter option selected. The platform filters the recommendation based on the category. The platform matches the category name against the You can also use a partial category name, since the API checks whether the category names in the database start with the string you provide here. For example:
| String | Optional | "category": "Books/Fiction/Fantasy" |
Search page context object
The following table describes the search object of the page context object. The search object provides context information about the current search page.
Table: Search page context object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
ids | IDs of the items returned by the current search. The IDs are relevant for strategies that use the Viewed together with recently searched items algorithm. The IDs are the target items against which the platform generates the recommendation. The platform matches the IDs against the The platform only uses the first three IDs in the list, so it's enough that you provide just three IDs. You're free to choose the logic by which you select the IDs. The logic could be, for example, always taking the IDs of the top three items in the search results. | Array of strings | Required | "ids": [ "958", "655", "358" ] |
categories | Names of the categories to which the returned items belong. The category names are relevant for strategies that use the Viewed together with recently searched categories algorithm. The platform generates the recommendation against the listed categories. The platform matches the category names against the The platform only uses the first three categories in the list, so it's enough that you provide the names of just three categories. You're free to choose the logic by which you select the categories. The logic could be, for example, always taking the categories of the top three items in the search results. You can also use partial category names, since the API checks whether the category names in the database start with the strings you provide here. For example:
| Array of strings | Required | "categories": [ "Books/Fiction/Fantasy", "Books/Fiction/Speculative" "Books/Fiction/Scifi" ] |
Request examples
Responses
Success
On a success, the Recommendations API returns the requested recommendation data in a JSON object. The response status code is 200.
The response object contains the following root properties:
data: Recommendation data as an array of objects, where each object contains the details of a single recommended item. Unless shuffled, the items are in descending order of rank, with the most recommended item (as defined by the algorithms) ranked highest.debug: Object containing the debugging information. This property is included only when thedebugparameter is set totruein the request.
{
"data": [
{<item 1 data>},
{<item 2 data>},
...
{<item n data>}
]
}
{
"data": [
{<item 1 data>},
{<item 2 data>},
...
{<item n data>}
],
"debug": {
<debugging information>
}
}
If an item is a parent product with one or more product variants, and if the request is set to also return variants, the recommended item object includes the variants array, which contains the full product data for each variant.
If there's no recommendation data available for the requested strategy, the API returns an empty array.
{
"data": []
}
Success examples
The following two examples show the same response without and with debugging information.
The following example shows a debug-enabled response for a strategy that applies visitor affinity.
Error
On an error, the Recommendations API returns the response status code 400 and an error message.
Table: Recommendations API error messages
| Error message | Description | Solution |
|---|---|---|
parameter 'method' missing | The method query parameter is missing from the request URL. | Provide the method query parameter. |
parameter 'method' contains an empty value | The value of the method query parameter is missing. | Provide a non-empty value for the method query parameter. |
invalid method '<parameter_value>' | The value of the method query parameter, <parameter_value>, is invalid. | Provide strategy as the value of the method query parameter. |
parameter 'origin' missing | The origin query parameter is missing from the request URL. | Provide the origin query parameter. |
parameter 'origin' contains an empty value | The value of the origin query parameter is missing. | Provide a non-empty value for the origin query parameter. |
invalid origin parameter '<parameter_value>' | The value of the origin query parameter, <parameter_value>, is invalid. | Provide a valid site origin as the value of the To find out your site's origin, see Getting your site origin. |
parameter 'strategy' missing | The strategy query parameter is missing from the request URL. | Provide the strategy query parameter. |
parameter 'strategy' contains an empty value | The value of the strategy query parameter is missing. | Provide a non-empty value for the strategy query parameter. |
invalid strategy parameter '<parameter_value>' | The value of the strategy query parameter, <parameter_value>, is invalid. | Provide a valid strategy ID as the value of the strategy query parameter. |
parameter 'cookieId' contains an empty value | The value of the cookieId query parameter is missing. | Provide a non-empty value for the cookieId query parameter. |
parameter 'cookieId' has invalid format | The value of the cookieId query parameter has an invalid format. | Provide a value that conforms to the following rules:
|
parameter 'context' missing | The context query parameter is missing from the request URL. | Provide the context query parameter. |
parameter 'context' contains an empty value | The value of the context query parameter is missing. | Provide a non-empty value for the context query parameter. |
parameter 'context' contains invalid JSON: <json_error> | The value of the context query parameter is not a valid JSON object. | Provide a valid JSON object as the value of the context query parameter. |
error retrieving value from context using path '<context_property_path>': expected string or array of strings for path: '<context_property_path>' | The value of the context query parameter does not contain the required context information, <context_property_path>, or one or more of the object properties containing the information are incorrectly named. | Make sure that the value of the context query parameter contains the required context information and that all the object properties are correctly named. |
parameter 'variants' invalid, expected either 'true', 'false', '1' or '0' | The value of the variants query parameter is invalid. | If you want to return product variant data, set the If you do not want to return product variant data, set the |
parameter 'affinityPercentage' invalid, expected value between 0 and 100 (inclusive) | The value of the affinityPercentage query parameter is invalid. | Set the value of the affinityPercentage query parameter to an integer that is greater than or equal to 0 and less than or equal to 100. |
parameter 'shuffle' invalid, expected either 'true', 'false', '1' or '0' | The value of the shuffle query parameter is invalid. | If you want to shuffle the order of items, set the If you do not want to shuffle the order of items, set the |
