Recommendations API reference (configurations)
Learn how to make Recommendations API requests to retrieve recommendation data generated from recommendation configurations.
If you want to retrieve recommendation data generated from recommendation strategies, see Recommendations API reference (strategies).
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:
-
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 following HTTP methods for recommendation configurations:
-
GET
-
POST
The only difference between the two is that with GET you provide the recommendation details in the request URL, while with POST you provide the details in the request body. If you're retrieving data for a recommendation configuration with a GET request, and the request URL exceeds the maximum URL length, use a POST request instead.
Syntax
GET
To retrieve recommendation data for a recommendation configuration using the GET method, make the following request:
GET https://<platform_instance>/recoApi/v2?method=multifetch&
origin=<site_origin>&
recos=[{
"name": "<recommendation_configuration_name>",
"params": {
"<parameter_1_name>": "<parameter_1_value>",
"<parameter_n_name>": "<parameter_n_value>"
}
}]
POST
To retrieve recommendation data for a recommendation configuration using the POST method, make the following request:
POST https://<platform_instance>/recoApi/v2?method=multifetch&
origin=<site_origin>
# REQUEST BODY
[{
"name": "<recommendation_configuration_name>",
"params": {
"<parameter_1_name>": "<parameter_1_value>",
"<parameter_n_name>": "<parameter_n_value>"
}
}]
Parameters
Parameter | Description | Type | Role | Example |
---|---|---|---|---|
| Request type. Use the value | String | Required |
|
| Site origin. To find out your site's origin, see Getting your site origin. | String | Required |
|
| Information about what recommendation data to retrieve and, if appropriate, how to filter the returned data with parameters defined in the recommendation configuration. You can retrieve the data for one or more recommendation configurations. You specify each configuration in its own recommendation configuration settings object using the JSON format. note The array must not be empty ( note If you want to guarantee a fast response, limit the number of recommendations to four. You can retrieve the data for five or more recommendations in the same request, if you want, but the platform may then take longer to respond. info The | Required (GET) | Retrieve the data for one recommendation configuration:
Retrieve the data for two recommendation configurations:
| |
| 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 |
|
| Define whether to return debugging information about the recommendation data. warning 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 |
|
Recommendation configuration settings object
The following table describes the recommendation configuration settings object of the recos
array. The object defines what recommendation data to retrieve and, if appropriate, how to filter the returned data.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| Recommendation configuration name. | String | Required |
|
| Request parameters defined in the recommendation configuration. Use the parameters to filter which recommended items to return. You can only include parameters defined in the recommendation configuration:
If the recommendation type is If the recommendation type is If you do not want to use any parameters to filter the recommendation results, omit this property from the request. | Object | Optional | For a
For a
For a
|
| Request parameter defined in the recommendation configuration. Use the parameter to filter which recommended items to return. You can define either a single string or an array of strings as the parameter value. In the latter case, the recommendation results are filtered separately by each string value. If the parameter corresponds to a source data field that has a Boolean or number value, such as product price, define the parameter value nonetheless as a string. For example, define the Boolean If you do not want to filter the results by the parameter, set the parameter value to an empty string ( | String | Array of strings | Required | Filter for
Filter for
Filter for
Filter by originally boolean and numeric values:
No filtering:
|
| warning This property is only valid for product recommendations. IDs of the products to exclude from the recommendation data. | Array of strings | Optional | Exclude products
|
| Maximum number of recommended items to return. By default, the platform uses the The minimum value is | Number | Optional |
|
| 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. By default, the platform uses the The possible values are:
| String | Optional |
|
Request examples
GET https://inpref.com/recoApi/v2?method=multifetch&
origin=shop_company_com&
recos=[{
"name": "Most viewed products",
"params": {
"type": "Books"
}
}]
POST https://inpref.com/recoApi/v2?method=multifetch&
origin=shop_company_com
# REQUEST BODY
[{
"name": "Most viewed products",
"params": {
"type": "Books"
}
}]
GET https://inpref.com/recoApi/v2?method=multifetch&
origin=shop_company_com&
recos=[{
"name": "Most viewed products",
"params": {
"type": "Books"
},
"excludeIds": [
"123",
"456",
"789"
]
}]
GET https://inpref.com/recoApi/v2?method=multifetch&
origin=shop_company_com&
recos=[{
"name": "Most viewed products",
"params": {
"type": "Books"
}
}]&
variants=true
GET https://inpref.com/recoApi/v2?method=multifetch&
origin=shop_company_com&
recos=[{
"name": "Most viewed products"
}]
GET https://inpref.com/recoApi/v2?method=multifetch&
origin=shop_company_com&
recos=[{
"name": "Most viewed products",
"params": {
"type": "Books"
}
},{
"name": "Most bought products",
"params": {
"type": "Books"
}
}]
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 arrays, where each array stores the data generated from a single recommendation configuration. -
debug
: Object containing the debugging information. This property is included only when thedebug
parameter is set totrue
in the request.
{
"data": [
[<configuration 1 data>],
[<configuration 2 data>],
...
[<configuration n data>]
]
}
{
"data": [
[<configuration 1 data>],
[<configuration 2 data>],
...
[<configuration n data>]
],
"debug": [
<debugging information>
]
}
The data for a recommendation configuration is returned as an array of objects, where each object contains the details of a single recommended item. The items are in descending order of rank, with the most recommended item (as defined by the algorithm) ranked highest.
# SINGLE RECOMMENDATION CONFIGURATION
{
"data": [
[
{<configuration 1 item 1 data>},
{<configuration 1 item 2 data>},
...
{<configuration 1 item n data>}
]
]
}
# MULTIPLE RECOMMENDATION CONFIGURATIONS
{
"data": [
[
{<configuration 1 item 1 data>},
{<configuration 1 item 2 data>},
...
{<configuration 1 item n data>}
],
[
{<configuration 2 item 1 data>},
{<configuration 2 item 2 data>},
...
{<configuration 2 item n data>}
]
]
}
Depending on the map_ids
parameter defined in the recommendation configuration, each item object contains either the raw recommendation data for the item (no mapping) or the full set of data retrieved from the Frosmo back end (mapping to data). For example, for a product when the ID is mapped, the object contains the full set of product data tracked for the product on the site.
# PRODUCT OBJECT (MAPPED TO PRODUCT DATA)
{
"data": [
[
{
"id": "123",
"type": "Books",
"name": "A Developer's Guide to Everything",
"created_at": "2018-11-08T10:45:15Z",
"updated_at": "2018-11-08T10:51:05Z",
"attributes": {
"image": "https://shop.company.com/products/123/images/123.png",
"price": "29.99",
"url": "https://shop.company.com/products/123"
}
}
]
]
}
# PRODUCT OBJECT (RAW RECOMMENDATION DATA)
{
"data": [
[
{
"id": "123",
"weight": 1056
}
]
]
}
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.
{
"data": [
[
{
"id": "1001",
"type": "Fashion/Shoes",
"name": "Casual Engineer Boots",
"created_at": "2022-01-14T17:36:37+02:00",
"updated_at": "2022-02-08T10:56:05+02:00",
"attributes": {
"availability": "in stock",
"brand": "Lumberland",
"color": "Black",
"image": "https://shop.company.com/images/products/product-1001.png",
"originalPrice": 350,
"price": 290,
"url": "https://shop.company.com/products/1001"
},
"variants": [
{
"id": "1002",
"type": "Fashion/Shoes",
"name": "Casual Engineer Boots",
"created_at": "2022-01-14T17:36:37+02:00",
"updated_at": "2022-02-08T10:56:20+02:00",
"attributes": {
"availability": "in stock",
"brand": "Lumberland",
"color": "Brown",
"image": "https://shop.company.com/images/products/product-1002.png",
"originalPrice": 350,
"price": 290,
"url": "https://shop.company.com/products/1002"
}
},
{
"id": "1003",
"type": "Fashion/Shoes",
"name": "Casual Engineer Boots",
"created_at": "2022-01-14T17:36:37+02:00",
"updated_at": "2022-02-08T10:56:34+02:00",
"attributes": {
"availability": "in stock",
"brand": "Lumberland",
"color": "White",
"image": "https://shop.company.com/images/products/product-1003.png",
"originalPrice": 350,
"price": 290,
"url": "https://shop.company.com/products/1003"
}
}
]
}
]
]
}
If there's no recommendation data available for the requested configuration, the API returns an empty array.
# SINGLE RECOMMENDATION CONFIGURATION WITH NO DATA
{
"data": [
[]
]
}
# MULTIPLE RECOMMENDATION CONFIGURATIONS, ONE WITH NO DATA
{
"data": [
[<configuration 1 data>],
[]
]
}
# MULTIPLE RECOMMENDATION CONFIGURATIONS, ALL WITH NO DATA
{
"data": [
[],
[]
]
}
Error
On an error, the Recommendations API returns the response status code 400
and an error message.
Error message | Description | Solution |
---|---|---|
| The | Make sure that the |
| The value of the | Use |
| The | Make sure that the |
| The value of the | Use a valid site origin as the value of the To find out your site's origin, see Getting your site origin. |
| The | Make sure that the |
| The The invalid value is located at: | Use a string as the array item value. |
| The value of the The invalid value is located at: | Use either a string or an array of strings as the value of the request parameter. |
| The value of the | Use a valid JSON array of objects as the value of the |
| The | Make sure that the |
| There's no recommendation data available for the | Make sure that the data for the |
| The value of the | If you want to return product variant data, set the If you do not want to return product variant data, set the |