Pages

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from this space and version 15.4

Learn how to make Recommendations API requests to retrieve recommendation data generated from recommendation configurations:

Table of Contents
maxLevel1

If you want to retrieve recommendation data generated from recommendation strategies, see Recommendations API reference (strategies).

Requests

Table of Contents
maxLevel3
minLevel2
excludeSuccess|Error

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:

  1. In the Frosmo Control Panel, select Utilities > Frosmo APIs.
  2. In the Recommendations API section, copy the URL.

    URL for Recommendations API requests

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:

Code Block
languagebash
themeRDark
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:

Code Block
languagebash
themeRDark
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

Table: Query parameters for Recommendations API requests (configurations)

ParameterDescriptionTypeRoleExample
method

Request type.

Use the value multifetch.

StringRequired


Code Block
languagebash
themeRDark
method=multifetch


origin

Site origin.

To find out your site's origin, see Getting your site origin.

StringRequired


Code Block
languagebash
themeRDark
origin=shop_company_com


recos

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 recos query parameter is only required for GET requests. POST requests pass the array of recommendation configuration settings objects in the request body. The rules for the objects nonetheless apply to both GET and POST requests.


Array of recommendation configuration settings objectsRequired (GET)

Retrieve the data for one recommendation configuration:

Code Block
languagebash
themeRDark
recos=[{
  "name": "Most viewed products",
  "params": {
    "type": "Books"
  }
}]

Retrieve the data for two recommendation configurations:

Code Block
languagebash
themeRDark
recos=[{
  "name": "Most viewed products",
  "params": {
    "type": "Books"
  }
},{
  "name": "Products viewed together",
  "params": {
    "id": "123"
  }
}]


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 variants array property of the recommended item object.

The possible values are:

  • false: Do not return product variant data.
  • true: Return product variant data.

The default value is false.

BooleanOptional


Code Block
languagebash
themeRDark
variants=true


debug

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:

  • false: Do not return debugging information.
  • true: Return debugging information.

The default value is false.

BooleanOptional


Code Block
languagebash
themeRDark
debug=true


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.

Table: Recommendation configuration settings object properties

PropertyDescriptionTypeRoleExample
nameRecommendation configuration name.StringRequired


Code Block
languagebash
themeRDark
"name": "Most viewed products"


params

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 you want to filter the results by a given parameter, assign the parameter an exact field or segment value (case insensitive).
  • If you do not want to filter the results by a given parameter, either omit the parameter or set the parameter value to an empty string ("").

If the recommendation type is bundle_viewed, bundle_converted, or bundle_viewed_converted, only include a single parameter: the target field against which the recommendation is generated, as defined in the recommendation configuration. For example, if you're recommending products purchased together with a product the visitor just added to their shopping cart, include the product ID parameter with a valid product ID as its value, since the recommendation is based on a specific product. Do not include any other parameters.

If the recommendation type is most_viewed or most_converted, include zero or more of the parameters defined in the recommendation configuration. The order of the parameters does not matter in the request. In addition, if you're filtering by segment, you can only define one segment per request.

If you do not want to use any parameters to filter the recommendation results, omit this property from the request.

ObjectOptional

For a bundle recommendation whose configuration defines the id parameter:

Code Block
languagebash
themeRDark
"params": {
  "id": "123"
}   

For a most recommendation whose configuration defines the type parameter:

Code Block
languagebash
themeRDark
"params": {
  "type": "Books"
}

For a most recommendation whose configuration defines the type and language parameters:

Code Block
languagebash
themeRDark
# Filter by type and language.

"params": {
  "type": "Books",
  "language": "English"
}

# Filter by type only.

"params": {
  "type": "Books",
  "language": ""
}

# Filter by neither, return all results.

"params": {
  "type": "",
  "language": ""
}

# Omitting "params" from the request yields the same result as the empty values above.


params.<parameter_name>

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 true as the string "true", and define the number 1 as the string "1".

If you do not want to filter the results by the parameter, set the parameter value to an empty string ("").

String | Array of stringsRequired

Filter for Books English:

Code Block
languagebash
themeRDark
"params": {
  "type": "Books",
  "language": "English"
}

Filter for Books English and Books Finnish:

Code Block
languagebash
themeRDark
"params": {
  "type": "Books",
  "language": [
    "English",
    "Finnish"
  ]
}

Filter for Books English, Books Finnish, Magazines English, and Magazines Finnish:

Code Block
languagebash
themeRDark
"params": {
  "type": [
    "Books",
    "Magazines"
  ],
  "language": [
    "English",
    "Finnish"
  ]
}

Filter by originally boolean and numeric values:

Code Block
languagebash
themeRDark
"params": {
  "isAvailable": "true",
  "price": "99.99"
}

No filtering:

Code Block
languagebash
themeRDark
"params": {
  "type": "",
  "language": ""
}


excludeIds


Note

This property is only valid for product recommendations.

IDs of the products to exclude from the recommendation data.

Array of stringsOptional

Exclude products 123, 456, and 789 from the recommendation data:

Code Block
languagebash
themeRDark
"excludeIds": [
  "123",
  "456",
  "789"
]


limit

Maximum number of recommended items to return.

By default, the platform uses the limit value defined in the recommendation configuration. If you want to set a different maximum for a request, define a limit in the request.

The minimum value is 1. The maximum value is 120.

NumberOptional


Code Block
languagebash
themeRDark
"limit": 5


mapping

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 map_ids value defined in the recommendation configuration. If you want to set a different mapping for a request, define a map_ids in the request.

The possible values are:

  • datapoint: Do not map the item IDs to anything. Return the raw recommendation data (ID and recommendation weight) for each item.
  • product: Map each item ID to a product ID. Return the full product data for each ID.
StringOptional


Code Block
languagebash
themeRDark
"mapping": ""


Request examples

Code Block
languagebash
themeRDark
titleExample: Single recommendation with filtering applied (GET)
collapsetrue
GET https://inpref.com/recoApi/v2?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": "Books"
      }
    }]


Code Block
languagebash
themeRDark
titleExample: Single recommendation with filtering applied (POST)
collapsetrue
POST https://inpref.com/recoApi/v2?method=multifetch&
     origin=shop_company_com

# REQUEST BODY

[{
  "name": "Most viewed products",
  "params": {
    "type": "Books"
  }
}]


Code Block
languagebash
themeRDark
titleExample: Single recommendation with filtering applied and selected results excluded (GET)
collapsetrue
GET https://inpref.com/recoApi/v2?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": "Books"
      },
      "excludeIds": [
        "123",
        "456",
        "789"
      ]
    }]


Code Block
languagebash
themeRDark
titleExample: Single recommendation with filtering applied and product variant data requested (GET)
collapsetrue
GET https://inpref.com/recoApi/v2?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": "Books"
      }
    }]&
    variants=true


Code Block
languagebash
themeRDark
titleExample: Single recommendation without any filtering applied (GET)
collapsetrue
GET https://inpref.com/recoApi/v2?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products"
    }]


Code Block
languagebash
themeRDark
titleExample: Multiple recommendations with filtering applied (GET)
collapsetrue
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

Table of Contents
maxLevel3
minLevel2
includeSuccess|Error

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 the debug parameter is set to true in the request.
Code Block
languagejs
themeRDark
titleResponse structure without debugging information
{
  "data": [
    [<configuration 1 data>],
    [<configuration 2 data>],
    ...
    [<configuration n data>]
  ]
}


Code Block
languagejs
themeRDark
titleResponse structure with debugging information
{
  "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.

Code Block
languagejs
themeRDark
# 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.

Code Block
languagejs
themeRDark
# 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.

Code Block
languagejs
themeRDark
titleResponse structure with product variant data
collapsetrue
{
  "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.

Code Block
languagejs
themeRDark
# 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.

Table: Recommendations API error messages

Error messageDescriptionSolution


Code Block
languagetext
themeRDark
parameter 'method' missing


The method query parameter is missing from the request URL or its value is undefined.Make sure that the method query parameter is properly defined.


Code Block
languagetext
themeRDark
invalid method '<parameter_value>'


The value of the method query parameter, <parameter_value>, is invalid.Use multifetch as the value of the method query parameter.


Code Block
languagetext
themeRDark
parameter 'origin' missing


The origin query parameter is missing from the request URL or its value is undefined.Make sure that the origin query parameter is properly defined.


Code Block
languagetext
themeRDark
invalid origin parameter '<parameter_value>'


The value of the origin query parameter, <parameter_value>, is invalid.

Use a valid site origin as the value of the origin query parameter.

To find out your site's origin, see Getting your site origin.


Code Block
languagetext
themeRDark
parameter 'recos' missing


The recos query parameter is missing from the request URL or its value is undefined.Make sure that the recos query parameter is properly defined.


Code Block
languagetext
themeRDark
parameter 'recos' contains invalid JSON: expected string for param name: '<parameter_name>', index: <parameter_index>, at recos index: <recos_index>


The <parameter_name> request parameter is an array that contains a value of the wrong type at the specified index. The API expects a string.

The invalid value is located at: recos[<recos_index>].params.<parameter_name>[<parameter_index>]

Use a string as the array item value.


Code Block
languagetext
themeRDark
parameter 'recos' contains invalid JSON: expected string or array of strings for param name: '<parameter_name>', at recos index: <recos_index>


The value of the <parameter_name> request parameter is of the wrong type. The API expects a string or an array of strings.

The invalid value is located at: recos[<recos_index>].params.<parameter_name>

Use either a string or an array of strings as the value of the request parameter.


Code Block
languagetext
themeRDark
parameter 'recos' contains invalid JSON: failed to parse


The value of the recos query parameter is not a valid JSON array of objects.Use a valid JSON array of objects as the value of the recos query parameter.


Code Block
languagetext
themeRDark
parameter 'recos' contains invalid JSON: invalid model '': recommendation not found


Code Block
languagetext
themeRDark
parameter 'recos' contains invalid JSON: invalid model '<name>': recommendation not found


The name property is missing from a recommendation object, or the value of the property is invalid or undefined.Make sure that the name property is properly defined with a valid value in each recommendation object.


Code Block
languagetext
themeRDark
invalid parameters '{"<key1>":"<value1>","<key2>":"<value2>"}' for model '<recommendation_configuration_name>': model not found


There's no recommendation data available for the <recommendation_configuration_name> recommendation configuration.Make sure that the data for the <recommendation_configuration_name> recommendation configuration has been successfully generated.


Code Block
languagetext
themeRDark
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 variants query parameter to either true or 1.

If you do not want to return product variant data, set the variants query parameter to either false or 0, or omit the parameter from the request URL.