Pages

Recommendations API v1 is deprecated. If you're currently using v1, migrate to v2. For more information, see Migrating to a new Recommendations API version.

Learn how to use Recommendations API v1:

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

Requests

URL

The URL for Recommendations API v1 requests is https://<platform_instance>/recoApi, 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 v1 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?method=multifetch&
    origin=<site_origin>&
    recos=[{
      "name": "<recommendation_configuration_name>",
      "<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?method=multifetch&
     origin=<site_origin>

# REQUEST BODY

[{
  "name": "<recommendation_configuration_name>",
  "<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",
  "type": "Books"
}]

Retrieve the data for two recommendations:

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

Table: Recommendation object properties

PropertyDescriptionTypeRoleExample
nameRecommendation name.StringRequired
"name": "Most viewed products"
<parameter_name>

Request parameter defined in the recommendation configuration. Use the parameter 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. You must either define values for all the parameters or leave all the values empty. In the latter case, the returned data is not filtered based on any parameters. 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.

StringRequired

For a bundle recommendation whose configuration defines the id parameter:

"id": "123"

For a most recommendation whose configuration defines the type parameter:

"type": "Books"

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

"type": "Books",
"language": "English"

Examples

Example: Retrieve a single recommendation and filter the results (GET)
GET https://<platform_instance>/recoApi/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "type": "Books"
    }]
Example: Retrieve a single recommendation and do not filter the results (GET)
GET https://<platform_instance>/recoApi/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "type": ""
    }]
Example: Retrieve two recommendations and filter the results (GET)
GET https://<platform_instance>/recoApi/?method=multifetch&
    origin=shop_company_com&
    recos=[{
      "name": "Most viewed products",
      "type": "Books",
    },{
      "name": "Most viewed products",
      "type": "Magazines"
    }]
Example: Retrieve two recommendations and filter the results (POST)
POST https://<platform_instance>/recoApi/?method=multifetch&
     origin=shop_company_com

# REQUEST BODY

[{
  "name": "Most viewed products",
  "type": "Books",
},{
  "name": "Most viewed products",
  "type": "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 one or more requested recommendations, the API returns an error.

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 JSONThe 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. For example:

recos=[{
  "name": "Most viewed products",
  "type": "Books"
}]
invalid model '<recommendation_configuration_name>'The name property is missing from a recommendation object defined in the recos query parameter 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 parameter.
invalid parameters '{"<key1>":"<value1>","<key2>":"<value2>"}' for model '<recommendation_configuration_name>'

This error is caused by invalid or missing data:

  • The set of request parameters defined in a recommendation object in the recos query parameter is invalid. Either one or more request parameters have invalid values, or one or more request parameters are missing.
  • One or more requested recommendations did not have any data to return. For example, if you request the data for four recommendations, and one of the recommendations has no data generated for it, the request fails with this error message.
Check that each recommendation object in the recos query parameter contains a valid set of request parameters. The request parameters must match what's defined in the corresponding recommendation configuration.

Troubleshooting

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

  • No labels