Smart Sorting & Reranking

Instead of relying solely on Froomle’s algorithms to generate recommendations from scratch, you can supply your own candidate items and let Froomle rank them using its personalization engine. This is useful when you already have a set of items (e.g. a curated editorial list or search results) and want to present them in the most relevant order for each user.

For full field specifications and examples, see the Recommendations API Reference.

How it works

Smart sorting uses the list_content field within a recommendation request list. You pass an array of candidate items, and Froomle returns them sorted by predicted relevance for the current user. Items have to be available to Froomle in order to be included in the final response with the appropriate metadata.

Unlike a regular recommendation request, Froomle will not fill remaining ranks with additional items when using smart sorting, i.e., passing in unranked items. If only ranked items are passed, Froomle will fill up the list to the requested size.

Request format

Each item in the list_content array accepts the following fields:

  • id (required, string): the client item ID.

  • item_type (required, string): the item type, if not the default.

Smart sorting request
{
  "page_type": "home",
  "channel": "www",
  "device_id": "device-123",
  "user_id": "user-123",
  "lists": [
    {
      "list_name": "reranked",
      "list_size": 10,
      "list_content": [
        {"id": "item-1", "item_type": "article"},
        {"id": "item-2", "item_type": "article"},
        {"id": "item-3", "item_type": "article"},
        {"id": "item-4", "item_type": "article"}
      ]
    }
  ]
}

The response follows the standard recommendation response format. Items are returned in order of predicted relevance.

Fixed-rank placement

You can also pin specific items to fixed positions by providing a rank field (1-indexed). The remaining positions are then filled with other recommendations from the engine rather than from your candidate list.

  • rank (optional, integer): the position at which the item must appear.

Request with fixed-rank items
{
  "page_type": "home",
  "channel": "www",
  "device_id": "device-123",
  "lists": [
    {
      "list_name": "curated_feed",
      "list_size": 6,
      "list_content": [
        {"id": "promo-article", "item_type": "article", "rank": 1},
        {"id": "sponsored-item", "item_type": "article", "rank": 4}
      ]
    }
  ]
}

In this example, promo-article is locked at position 1 and sponsored-item at position 4. Positions 2, 3, 5, and 6 are filled by the recommendation engine.

Use fixed-rank placement to guarantee visibility for sponsored or editorial content while still personalizing the rest of the list.

Combining both modes

You can mix free-ranked and fixed-rank items in the same list. Items with a rank are pinned; items without a rank are reranked by the engine among the remaining positions.

Combined request
{
  "page_type": "article_detail",
  "channel": "www",
  "device_id": "device-123",
  "context_item": "article_789",
  "context_item_type": "article",
  "lists": [
    {
      "list_name": "related",
      "list_size": 8,
      "list_content": [
        {"id": "item-1", "item_type": "article", "rank": 1},
        {"id": "item-2", "item_type": "article"},
        {"id": "item-3", "item_type": "article"},
        {"id": "item-4", "item_type": "article"}
      ]
    }
  ]
}

Related topics