Pages

Once you've created a recommendation, you can retrieve the generated recommendation data through the Recommendations API:

For the complete API specification, including detailed information about request parameters and error responses, see the Recommendations API guide.

Requests

Basics

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 find out the domain name, see the Recommendations API guide.

The API does not require authentication.

The 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

PropertyDescriptionTypeRoleExample
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

On success, the Recommendations API returns the recommendation data in the JSON format. For information about error responses, see the Recommendations API guide.

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

# SINGLE RECOMMENDATION

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

# MULTIPLE RECOMMENDATIONS

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

Depending on the map_ids parameter defined for the recommendation, each product object contains either the raw recommendation data for the product (no mapping) or the full set of product data retrieved from the Frosmo back end (mapping to data).

# 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
      }
    ]
  ]
}
  • No labels