Pages

Learn how to use Recommendations API v2:

For an overview of the Recommendations API, see Recommendations API.

For instructions on how to migrate from v1 to v2, see Migrating to a new Recommendations API version.

Requests

URL

The URL for Recommendations API v2 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.

    Base URL for Recommendations API v2 requests

Authentication

The Recommendations API does not require authentication.

HTTP methods

The Recommendations API supports the following standard HTTP methods:

  • 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 your GET request URL exceeds the maximum URL length, use a POST request instead.

Usage

To retrieve recommendation data using the GET method, make the following request:

GET
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>"
      }
    }]

To retrieve recommendation data using the POST method, make the following request:

POST
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

ParameterDescriptionTypeRoleExample
method

Request type.

The possible values are:

  • multifetch to retrieve recommendation data using GET or POST
StringRequired
method=multifetch
origin

Site origin.

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

StringRequired/Optional
origin=shop_company_com
recos

Information about what recommendation data to retrieve and, if appropriate, how to filter the returned data.

You can retrieve the data for one or more recommendations. You specify each recommendation in its own JSON object.

The array must not be empty ([]).

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.

The recos query parameter is only required for GET requests. POST requests pass the array of recommendation objects in the request body. The above rules for recommendation objects nonetheless apply to both GET and POST requests.

Array of recommendation objects (JSON)Required/Optional

Retrieve the data for one recommendation:

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

Retrieve the data for two recommendations:

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

Table: Recommendation object properties

PropertyDescriptionTypeRoleExample
nameRecommendation name.StringRequired
"name": "Most viewed products"
params

Request parameters defined in the recommendation configuration. Use the parameters to filter the generated recommendation data.

You must include each parameter defined in the recommendation configuration.

If your recommendation type is bundle_viewed, bundle_converted, or bundle_viewed_converted, only include the product ID parameter with a valid ID value.

If your recommendation type is most_viewed or most_converted, include each parameter defined in the recommendation configuration. If you do not want to filter the returned data by a specific parameter, set its value to an empty string. The returned data is filtered based on only those parameters for which you define a proper, non-empty value. 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.

ObjectRequired

For a bundle recommendation whose configuration defines the id parameter:

"params": {
  "id": "123"
}

For a most recommendation whose configuration defines the type parameter:

"params": {
  "type": "Books"
}

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

# Filter by type and language

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

# Filter by type only

"params": {
  "type": "Books",
  "language": ""
}
params.<parameter_name>

Request parameter defined in the recommendation configuration. Use the parameter to filter the generated recommendation data.

You can define either a single string or an array of strings as the parameter value. In the latter case, the recommendation data is filtered separately by each string value.

If a parameter maps to a source data field that has a Boolean or number value, such as product price, you nonetheless define the parameter value as a string. For example, define the Boolean true as the string "true", and define the number 1 as the string "1".

String or array of stringsRequired

Filter for Books English:

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

Filter for Books English and Books Finnish:

"params": {
  "type": "Books",
  "language": ["English", "Finnish"]
}

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

"params": {
  "type": ["Books", "Magazines"],
  "language": ["English", "Finnish"]
}

Filter by originally boolean and numeric values:

"params": {
  "isAvailable": "true",
  "price": "99.99"
}

No filtering:

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

IDs of the products to exclude from the recommendation data.

This property is only valid for product recommendations.

Array of stringsOptional

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

"excludeIds": ["123", "456", "789"]

Examples

Example: Retrieve a single recommendation and filter the results (GET)
GET https://<platform_instance>/recoApi/v2/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": "Books"
      }
    }]
Example: Retrieve a single recommendation, filter the results, and exclude selected results (GET)
GET https://<platform_instance>/recoApi/v2/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": "Books"
      },
      "excludeIds": ["123", "456", "789"]
    }]
Example: Retrieve a single recommendation and do not filter the results (GET)
GET https://<platform_instance>/recoApi/v2/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": ""
      }
    }]
Example: Retrieve two recommendations and filter the results (GET)
GET https://<platform_instance>/recoApi/v2/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": "Books"
      }
    },{
      "name": "Most viewed products",
      "params": {
        "type": "Magazines"
      }
    }]
Example: Retrieve the same data as above but in a single recommendation (GET)
GET https://<platform_instance>/recoApi/v2/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "params": {
        "type": ["Books", "Magazines"]
      }
    }]
Example: Retrieve two recommendations and filter the results (POST)
POST https://<platform_instance>/recoApi/v2/?method=multifetch&
     origin=shop_company_com

# REQUEST BODY

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

Responses

Success

On success, the Recommendations API returns the recommendation data in the JSON format. The response status code is 200.

The response body is an object that contains the data array. Each item in the data array stores the data for a single recommendation.

{
  "data": [
    [<recommendation 1 data>],
    [<recommendation 2 data>],
    ...
    [<recommendation n data>]
  ]
}

The data for a single recommendation is returned as an array of objects, where each object contains the data for a single recommended item, such as a product.

# SINGLE RECOMMENDATION

{
  "data": [
    [
      {<item 1 data>},
      {<item 2 data>},
      ...
      {<item n data>}
    ]
  ]
}

# MULTIPLE RECOMMENDATIONS

{
  "data": [
    [
      {<item 1 data>},
      {<item 2 data>},
      ...
      {<item n data>}
    ],
    [
      {<item 1 data>},
      {<item 2 data>},
      ...
      {<item n data>}
    ]
  ]
}

Depending on the map_ids parameter defined for the recommendation, 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 there's no data for a requested recommendation, the API returns an empty array for that recommendation.

# SINGLE RECOMMENDATION WITH NO DATA

{
  "data": [
    []
  ]
}

# MULTIPLE RECOMMENDATIONS, ONE WITH NO DATA

{
  "data": [
    [<recommendation 1 data>],
    []
  ]
}

# MULTIPLE RECOMMENDATIONS, ALL WITH NO DATA

{
  "data": [
    [],
    []
  ]
}

For more information about how the ID gets mapped to product data, see the data point documentation in Recommendations.

Error

On an error, the Recommendations API returns the response status code 400 and an error message.

Table: Recommendations API error messages

Error messageDescriptionSolution
parameter 'method' missingThe method query parameter is missing from the request URL or its value is empty.Check that the method parameter is properly defined.
invalid method '<parameter_value>'The value of the method query parameter, <parameter_value>, is invalid.Provide multifetch as the method parameter value.
parameter 'origin' missingThe origin query parameter is missing from the request URL or its value is empty.Check that the origin parameter is properly defined.
invalid origin-parameter '<parameter_value>'The value of the origin query parameter, <parameter_value>, is invalid.Provide a valid site origin as the origin parameter value. To find out your site's origin, see Getting your site origin.
parameter 'recos' missingThe recos query parameter is missing from the request URL or its value is empty.Check that the recos parameter is properly defined.
parameter 'recos' contains invalid JSON: expected string for param: '<parameter_name>', index: <number>, at recos index: <number>

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

The parameter is located in the params object of the recommendation object at the specified index in the recos array.

Provide a string as the array item value.
parameter 'recos' contains invalid JSON: expected string or array of strings for param: '<parameter_name>', at recos index: <number>

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

The parameter is located in the params object of the recommendation object at the specified index in the recos array.

Provide either a string or an array of strings as the parameter value.
parameter 'recos' contains invalid JSON: failed to parseThe value of the recos query parameter is not a valid JSON array of objects.Provide a valid JSON array of objects as the recos parameter value.
parameter 'recos' contains invalid JSON: missing params, at recos index: <number>The params object of the recommendation object at the specified index in the recos array is empty.Provide one or more parameters in the params object, as per the recommendation configuration. The recommendation configuration must define at least one parameter for filtering the recommendation data.
invalid model '<recommendation_name>'The name property is missing from a recommendation object defined in the recos array, or the property value is invalid or empty.Check that the name property is properly defined with a valid value in each recommendation object in the recos array.
invalid parameters '{"<key1>":"<value1>","<key2>":"<value2>"}' for model '<recommendation_name>': model not foundThere's no recommendation data available for the specified recommendation.Check that the <recommendation_name> recommendation exists, and make sure it's data has been generated.
invalid parameters '{"<key1>":"<value1>","<key2>":"<value2>"}' for model '<recommendation_name>': missing required parameter '<parameter_name>'The set of request parameters does not match what's defined in the corresponding recommendation configuration: the required <parameter_name> parameter is not defined in the request.Define the <parameter_name> parameter in the params object from where it's missing.

Troubleshooting

If the Recommendations API returns an error or otherwise fails to return the data you expect, try the following:

  • No labels