Pages

For an introduction to retrieving recommendation data generated from recommendation strategies, see Retrieving recommendation data for strategies.

Learn how to make Recommendations API requests to retrieve recommendation data for strategies:

See also Recommendations API: Responses (strategies).

The API does not currently support algorithms that require context information about the current visitor. You cannot use the API to retrieve recommendation data for strategies that use these algorithms.

You can also retrieve recommendation data for strategies using the frosmo.easy.strategies.fetch() JavaScript function. The function supports all algorithms. For more information, see Retrieving recommendation data for strategies.

If you want to retrieve recommendation data generated from recommendation configurations, see Recommendations API: Requests (configurations).

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 GET HTTP method for recommendation strategies.

Syntax

To retrieve recommendation data for a recommendation strategy, make the following GET request:

GET https://<platform_instance>/recoApi/v2?method=strategy&
    origin=<site_origin>&
    strategy=<strategy_id>&
    context={<strategy_context>}

Parameters

Table: Query parameters for Recommendations API requests

ParameterDescriptionTypeRoleExample
method

Request type.

Use the value strategy.

StringRequired
method=strategy
origin

Site origin.

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

StringRequired
origin=shop_company_com
strategyRecommendation strategy ID.StringRequired
strategy=product-page--recommended-for-you
cookieId

Local Frosmo ID of the visitor who sees the recommendation returned by the API request.

This parameter is required if (a) the strategy is set to apply some level of visitor affinity or (b) you want to apply affinity in the API request even if the strategy is not set to apply affinity. The ID allows the platform to use the visitor's affinity profile for personalizing the recommendation for the visitor.

This parameter has no effect if the strategy is not set to apply affinity or if affinityPercentage is not defined.

StringOptional
cookieId=dsr77t.kstzihlx
context

Information about the context into which the recommendation data is retrieved. The context consists of information about the current page (where the API request is made).

The context allows the API to return the correct recommendation data for the current page. The exact context information required depends on the page type of the recommendation strategy: the context must match the page type.

You specify the context object using the JSON format.

Some algorithms require a user context, which provides information about the current visitor (whom the recommendation must target). The API does not currently support these algorithms nor strategies that use them.

Recommendation strategy context objectRequired
# Product page context

context={
  "page": {
    "product": {
      "id": "719",
      "category": "Books/Fiction/Fantasy"
    }
  }
}
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
variants=true
affinityPercentage

Level of visitor affinity (in percentages) applied to the recommendation. The higher the level, the more personalized the set of recommended items is for each individual visitor.

The minimum value is 0 (no affinity applied, an algorithm fully determines how the items it returns are ranked). The maximum value is 100 (affinity fully determines how the items returned by an algorithm are ranked).

If defined, this parameter overrides the level of affinity set in the strategy.

This parameter has no effect unless cookieId is also defined.

NumberOptional
affinityPercentage=50
shuffle

Define whether to randomly shuffle the order of items in the recommendation data.

By default, the items are in descending order of rank, with the most recommended item (as defined by the recommendation strategy) ranked highest.

The possible values are:

  • false: Do not shuffle the order of items.
  • true: Shuffle the order of items.

The default value is false.

If any affinity is applied, shuffling is disabled, irrespective of the value of this parameter. Affinity is applied when cookieId is defined, and the level of affinity is set to greater than 0% either in the strategy or with affinityPercentage.

BooleanOptional
shuffle=true
debug

Define whether to return debugging information about the recommendation data.

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
debug=true

Recommendation strategy context object

The following table describes the context object for recommendation strategies. The object provides information about the context into which the recommendation data is retrieved.

Table: Recommendation strategy context object properties

PropertyDescriptionTypeRoleExample
pageContext information about the current page.Page context objectRequired
# Page context object for a product page

"page": {
  "product": {
    "id": "719",
    "category": "Books/Fiction/Fantasy"
  }
}

Page context object

The following table describes the page object of the recommendation strategy context object. The page object provides context information about the current page.

The page context must match the page type of the recommendation strategy.

Table: Page context object properties

PropertyDescriptionTypeRoleExample
cartContext information about the current shopping cart page.Cart page context objectOptional
"cart": {
  "ids": [
    "958",
    "175",
    "280"
  ]
}
categoryContext information about the current category page.Category page context objectOptional
"category": {
  "name": "Books/Fiction/Fantasy",
  "categories": [
    "Books/Fiction/Fantasy",
    "Books/Fiction/Speculative"
  ]
}
product

Context information about the current product page.

Here, "product" refers to any item that a site sells or offers to visitors, or that the site otherwise tracks for conversions or transactions. A product can be, for example, a retail product, a blog article, an online game, a magazine subscription, or a downloadable brochure.

Product page context objectOptional
"product": {
  "id": "719",
  "category": "Books/Fiction/Fantasy"
}
searchContext information about the current search page.Search page context objectOptional
"search": {
  "ids": [
    "958",
    "655",
    "358",
    "809",
    "955"
  ],
  "categories": [
    "Books/Fiction/Fantasy",
    "Books/Fiction/Speculative"
    "Books/Fiction/Scifi"
  ]
}

Cart page context object

The following table describes the cart object of the page context object. The cart object provides context information about the current shopping cart page.

Table: Cart page context object properties

PropertyDescriptionTypeRoleExample
ids

IDs of the items currently in the visitor's shopping cart.

The IDs are relevant for strategies that use a Bought together with item added to cart algorithm. The IDs are the target items against which the platform generates the recommendation.

The platform matches the IDs against the id attribute value tracked for an item.

The platform currently only uses the first ID in the list, so it's enough that you provide just a single ID. You're free to choose the logic by which you select the ID. The logic could be, for example, always taking the ID of the last item added to the cart.

Array of stringsRequired
"ids": [
  "958"
]

Category page context object

The following table describes the category object of the page context object. The category object provides context information about the current category page.

Table: Category page context object properties

PropertyDescriptionTypeRoleExample
categories

Names of the categories whose items are shown on the current category page.

The category names are relevant for strategies that use a Bought together with current category or Viewed together with current category algorithm, or that have an Only return items filter option selected. The platform generates the recommendation against the listed categories.

The platform matches the category names against the type attribute value tracked for an item. If a strategy has the Only return items whose categories include the viewed category filter option selected, the platform filters the recommendation based on categories attribute values.

You can also use partial category names, since the API checks whether the category names in the database start with the strings you provide here.

For example:

  • "Music" matches Music, Musical Instruments, and any other category name that starts with "Music".
  • "Books/Fiction" matches Books/Fiction/FantasyBooks/Fiction/Speculative, and any other category name that starts with "Books/Fiction".

Examples

  • If the Furnishing category page shows items from the Blankets, Curtains, and Rugs categories, list those three category names here.
  • If the Books/Fiction category page shows items from the Books/Fiction/Fantasy, Books/Fiction/Speculative, and Books/Kids/Fiction categories, list those three category names here.
  • If the Books/Fiction category page instead only shows items from categories starting with "Books/Fiction", simply list Books/Fiction here.
Array of stringsRequired
"categories": [
  "Books/Fiction/Fantasy",
  "Books/Fiction/Speculative",
  "Books/Kids/Fiction"
]

Product page context object

The following table describes the product object of the page context object. The product object provides context information about the current product page.

Table: Product page context object properties

PropertyDescriptionTypeRoleExample
id

Item ID.

The ID is relevant for strategies that use a Bought together with current item or Viewed together with current item algorithm. The ID is the current item against which the platform generates the recommendation.

The platform matches the ID against the id attribute value tracked for an item.

StringRequired
"id": "719"
category

Name of the category to which the item belongs.

The category name is relevant for strategies that have an Only return items filter option selected. The platform filters the recommendation based on the category.

The platform matches the category name against the type attribute value tracked for an item. If a strategy has the Only return items whose categories include at least one category to which the viewed item belongs filter option selected, the platform filters the recommendation based on categories attribute values.

You can also use a partial category name, since the API checks whether the category names in the database start with the string you provide here.

For example:

  • "Music" matches Music, Musical Instruments, and any other category name that starts with "Music".
  • "Books/Fiction" matches Books/Fiction/FantasyBooks/Fiction/Speculative, and any other category name that starts with "Books/Fiction".
StringOptional
"category": "Books/Fiction/Fantasy"

Search page context object

The following table describes the search object of the page context object. The search object provides context information about the current search page.

Table: Search page context object properties

PropertyDescriptionTypeRoleExample
ids

IDs of the items returned by the current search.

The IDs are relevant for strategies that use a Viewed together with recently searched items algorithm. The IDs are the target items against which the platform generates the recommendation.

The platform matches the IDs against the id attribute value tracked for an item.

The platform only uses the first three IDs in the list, so it's enough that you provide just three IDs. You're free to choose the logic by which you select the IDs. The logic could be, for example, always taking the IDs of the top three items in the search results.

Array of stringsRequired
"ids": [
  "958",
  "655",
  "358"
]
categories

Names of the categories to which the returned items belong.

The category names are relevant for strategies that use a Viewed together with recently searched categories algorithm. The platform generates the recommendation against the listed categories.

The platform matches the category names against the type attribute value tracked for an item.

The platform only uses the first three categories in the list, so it's enough that you provide the names of just three categories. You're free to choose the logic by which you select the categories. The logic could be, for example, always taking the categories of the top three items in the search results.

You can also use partial category names, since the API checks whether the category names in the database start with the strings you provide here.

For example:

  • "Music" matches Music, Musical Instruments, and any other category name that starts with "Music".
  • "Books/Fiction" matches Books/Fiction/FantasyBooks/Fiction/Speculative, and any other category name that starts with "Books/Fiction".
Array of stringsRequired
"categories": [
  "Books/Fiction/Fantasy",
  "Books/Fiction/Speculative"
  "Books/Fiction/Scifi"
]

Examples

Example: Product page recommendation
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=viewed-together-with-current-item&
    context={
      "page": {
        "product": {
          "id": "719",
          "category": "Books/Fiction/Fantasy"
        }
      }
    }
Example: Product page recommendation, return product variant data
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=viewed-together-with-current-item&
    context={
      "page": {
        "product": {
          "id": "719",
          "category": "Books/Fiction/Fantasy"
        }
      }
    }&
    variants=true
Example: Product page recommendation, affinity applied
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=viewed-together-with-current-item-with-affinity&
    cookieId=dsr77t.kstzihlx&
    context={
      "page": {
        "product": {
          "id": "719",
          "category": "Books/Fiction/Fantasy"
        }
      }
    }
Example: Product page recommendation, affinity applied, custom affinity percentage
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=viewed-together-with-current-item-with-affinity&
    cookieId=dsr77t.kstzihlx&
    context={
      "page": {
        "product": {
          "id": "719",
          "category": "Books/Fiction/Fantasy"
        }
      }
    }&
    affinityPercentage=30
Example: Category page recommendation
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=bought-together-with-current-category&
    context={
      "page": {
        "category": {
          "categories": [
            "Books/Fiction/Fantasy",
            "Books/Fiction/Speculative"
          ]
        }
      }
    }
Example: Home page ("other") recommendation
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=trending-on-site&
    context={}