How to generate recommendations

Requesting recommendations

Real-time recommendations for display on a web page or in an app can be requested through the recommendations API endpoint. Requests are to be sent as POST request with a JSON body (Content-Type: application/json).

A request can contain some context in which it is made, such as the user’s ID, the type of page they are on, the item they are viewing, and so on. For each kind of webpage the request can be tailored to match its exact context. Below you find an example recommendation request for three common page types.

  • Homepage

  • Category page

  • Detail page

{
  "page_type": "home",
  "channel": "website",
  "device_id": "BD3qoN3ko7URdparQX2vDT4",
  "user_id": "7081599607",  (1)
  "lists": [
    {
      "list_name": "You may also like",
      "configuration_id": "a-homepage-config-id",
      "list_size": 10
    },
    {
      "list_name": "Popular items",
      "configuration_id": "popular",
      "list_size": 10,
      "limit": 5,
      "list_content": [
        {"id": "item-1", "rank": 1},
        {"id": "item-2", "rank": 2}
      ]
    }
  ]
}
{
  "page_type": "category",
  "channel": "website",
  "device_id": "BD3qoN3ko7URdparQX2vDT4",
  "user_id": "7081599607",  (1)
  "lists": [
    {
      "list_name": "You may also like",
      "configuration_id": "a-category-config-id",
      "list_size": 10
    },
    {
      "list_name": "Popular items",
      "configuration_id": "popular",
      "list_size": 10,
      "limit": 5
    }
  ]
}
{
  "page_type": "product_detail",
  "channel": "website",
  "device_id": "BD3qoN3ko7URdparQX2vDT4",
  "user_id": "7081599607",  (1)
  "context_item": "917096",  (1)
  "lists": [
    {
      "list_name": "You may also like",
      "configuration_id": "a-config-id",
      "list_size": 10
    },
    {
      "list_name": "Popular items",
      "configuration_id": "popular",
      "list_size": 10,
      "limit": 5
    }
  ]
}
1 We always expect a string representation for item and user identifiers.

An explanation of the different fields:

  • page_type: This is the type of page the user is on.

  • channel: This is a description of how the user is accessing the page, like website, mobile_website, or app.

  • context_item: This is the ID of the item displayed on the current page. We can use this to show recommendations related to the product the user is viewing. This field is not present in home or category requests as there is no currently viewed item present.

  • user_id: This is the long-term identification of the user, such as a login ID. This identifier should not contain any personal information, e.g. email address.

  • device_id: This is the identification of the user’s device, such as a cookie ID. Used as a fallback when there is no user_id available.

Froomle recommends you send a single request per page where Froomle is integrated in your app or website. You might want to display Froomle recommendations in more than one section of your page. For this purpose, each recommendation request defines one or more lists. Each list in the request will be filled with recommendations, and each can be configured differently.

  • list_name: This lets you define an identifier for a list. We don’t interpret this name, but we will echo it back in our recommendation response, such that there is no confusion which recommendations belong to which list. A list name should be unique within a request.

  • configuration_id: This defines which previously defined set of constraints to apply to the recommendations. These sets of constraints can be managed through the configurations API. Though Froomle can manage these for you, we encourage you to define your own, as this provides an easy way of customizing the results to your liking.

  • list_size: This defines the number of recommendations to be generated for this list. Note that when there are not enough items that satisfy the constraints, fewer than list_size items will be returned.

  • limit (optional): This specifies the number of recommendations to be included in the response to this request. The remaining (list_sizelimit) recommendations (or any other subset of the recommendations) can be retrieved later using the lists endpoint. If not given, then limit = list_size.

  • list_content (optional): Includes specific items at given positions in the resulting recommendation list. rank specifies the position of the item in the list, where the first position has rank 1, the second has rank 2, and so on.

The response, then, is structured as follows:

{
  "device_id": "BD3qoN3ko7URdparQX2vDT4",
  "user_id": "7081599607",
  "request_id": 4567,
  "user_group": "froomle",
  "version": "Froomle_1",
  "lists": [
    {
      "list_key" : "sdjfkls12nfdls",
      "list_name" : "You may also like",
      "configuration_id": "a-config-id",
      "list_size" : 10,
      "items" : [
          {
            "rank": 1,
            "product" : "948451",
          },
          {
            "rank": 2,
            "product" : "643321"
          },
          ...
      ]
    },
    ...
  ]
}
  • device_id, user_id, list_name, configuration_id, and list_size are echoed back from the request.

  • user_group: This equals froomle if the user is in a user group that receives Froomle recommendations.

  • version: This specifies in which A/B group the user is currently enrolled.

  • request_id: This is an integer that should be sent when an event occurs that is related to this recommendation request, such as click_on_recommendation or impression. Thus, it is important to have this value readily available.

  • list_key: This uniquely identifies this list of recommendations, and can be used to later retrieve the remaining (list_sizelimit) items, or any subset of the recommendations, using the lists endpoint.

  • items contains the IDs of the recommended items. The items are ordered by relevance, with the most relevant item listed first.

Getting started

As soon as your Recommendations API has been activated by the Froomle engineering team at https://customer_token.froomle.com/api/environment/recommendations/requests, you can start testing the API. Navigate to https://customer_token.froomle.com/api/ui and open up the recommendations section. The UI supplies an example recommendation request that should work out of the box, given that you have obtained the required authentication credentials. To request these authentication credentials, please contact the Froomle support team at support@froomle.com.

Retrieving cached recommendations

In certain cases it can be useful to retrieve previously requested recommendations; for instance when initially not all requested recommendations will be visible, or when you would like to present the user with a set of recommendations they saw earlier. This is possible with the lists API endpoint, which gives access to a cache of previously generated recommendations.

Requests to the lists endpoint don’t have a body. All parameters are URL-encoded.

All parameters are required:

  • list_key: The list key of recommendations to retrieve, as given in the response body of the recommendation request.

  • offset: The rank of the first recommendation that is to be returned.

  • limit: The number of subsequent recommendations that are to be returned.

Examples:

  • offset = 1, limit = 3 returns recommendations with ranks 1 (most relevant), 2, 3:

    [
      {
        "rank": 1,
        "product" : "948451",
      },
      {
        "rank": 2,
        "product" : "643321"
      },
      {
        "rank": 3,
        "product": "374890"
      }
    ]
  • offset = 7, limit = 5 returns recommendations with ranks 7, 8, 9, 10, and 11.

If offset + limit – 1 is greater than the number of recommendations generated for the list, then the remaining recommendations will be returned, which will be fewer than specified. If offset > list_size, then no items will be returned.