Recommendation Requests

The Froomle engine generates one or more sets of recommendations for every request you send. By providing context about the user and their current environment, you allow our algorithms to select the optimal content from your catalog.

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

Core Request Structure

To get recommendations, you must define the modules you want to fill and the context of the request.

In Froomle, a Module refers to the logical placement on your page (e.g., the "slot"), whereas a List refers to the specific configuration and data we return to fill that slot.

 
{
  "lists": [
    { "list_name": "recommended_for_you", "list_size": 10 },
    { "list_name": "editor_picks", "list_size": 4 }
  ],
  "page_type": "home",
  "channel": "www-desktop",
  "device_id": "device_123"
}

Repeating List Names

In some scenarios, you may want to request the same algorithm or module multiple times with different parameters (e.g., showing "Recommended for You" filtered by three different categories).

While list_name must be unique in simple requests, you can repeat them by providing a unique alias for each instance. This alias is returned in the response, allowing your frontend to distinguish between the resulting lists.

You can also pass specific parameters—like categories—within each list to override or augment the default module behavior for that specific request.

Request with repeated list names and aliases
{
  "lists": [
    {
      "list_name": "recommended_for_you",
      "categories": ["sports"],
      "alias": "reco_sports",
      "list_size": 5
    },
    {
      "list_name": "recommended_for_you",
      "categories": ["news"],
      "alias": "reco_news",
      "list_size": 5
    }
  ],
  "page_type": "home",
  "channel": "www-desktop",
  "device_id": "device_123"
}
Sample Response showing aliases
{
  "lists": [
    {
      "list_name": "recommended_for_you",
      "alias": "reco_sports",
      "recommendations": [...]
    },
    {
      "list_name": "recommended_for_you",
      "alias": "reco_news",
      "recommendations": [...]
    }
  ]
}

Providing Context

Sharing the user’s current context allows Froomle to anchor its recommendations to their immediate intent. The most critical anchor is the Context Item.

  • context_item: The stable ID of the item the user is currently interacting with (e.g., the article they are reading).

  • context_item_type: The type of the context item (e.g., article, product). This field is mandatory whenever a context_item is provided.

Automatic Context-Based Filtering

By providing a context item, you can leverage backend rules that apply filters automatically based on that item’s metadata. This ensures consistency without requiring complex request-side logic.

The context_item must already exist in your Item Catalog. If the ID is not synchronized, Froomle cannot look up its metadata to apply automatic rules.

Examples:

  • Content Consistency: "Only recommend articles in the same primary category as the context item."

  • Value Alignment: "Only recommend products within the same price bracket as the item currently in view."

Deduplication

Froomle provides several mechanisms to ensure that users receive a diverse and relevant set of recommendations without unnecessary repetition within a single page or session.

Automatic Cross-List Uniqueness

By default, Froomle ensures that the same item is never repeated across different modules (lists) in a single request.

For example, if you request both a "Trending" list and a "Recommended for You" list in one API call, an item that appears in the first list will be automatically disqualified from appearing in the second. This prevents redundant content and maximizes the surface area for discovery.

Manual Contextual Exclusions

Manual exclusions (also called In-Page Deduplication) allow you to filter out specific items that are already visible to the user elsewhere on the page, such as the main article being read or a manually curated "Hero" banner.

Froomle uses the histories object to track facts about the user’s current session or state—including items they should be excluded from seeing right now.

To exclude items, you define a dedicated key (traditionally exclude) within the histories object. Each item in this list must have its reconsumable property set to false.

You can also use this logic to exclude items the user has already interacted with (e.g., items already in their shopping basket) by creating a history called items_in_basket with reconsumable: false.
Request with manual exclusions
{
  "channel": "www-desktop",
  "device_id": "device_123",
  "page_type": "article_detail",
  "context_item": "article_456",
  "context_item_type": "article",
  "histories": {
    "exclude": [
      { "id": "article_456", "item_type": "article", "reconsumable": false },
      { "id": "hero_article_789", "item_type": "article", "reconsumable": false }
    ]
  },
  "lists": [
    { "list_name": "trending", "list_size": 5 }
  ]
}

Technical Placement

Exclusions are passed within the histories object at the root of the request. These exclusions apply to all modules/lists requested in that call.

Exclusions vs. Filters: Use the exclude history when you have a list of specific IDs to remove. Use Filters when you want to remove whole categories of items (e.g., "Exclude all items priced > $100").

Driving the Engine with Filters

Requests are the entry point for your business logic. By passing specific values in your request, you can drive complex filtering and boosting rules configured in our backend.

Read the Filters and Constraints guide to learn how request fields map to your item metadata for precise control.

Default Behaviors

Froomle comes with sensible defaults to ensure a high-quality experience:

  • No-Repeat Filtering: By default, Froomle will not recommend items that the user has already viewed (based on their interaction history).

  • Business Rules: Items that are unpublished or archived in your catalog are automatically removed from the eligible pool.

Customizable Responses

The recommendation response is not just a list of IDs. Froomle can return any synchronized metadata (e.g., titles, images, price) directly in the response.

Returning metadata in the response simplifies your frontend integration by eliminating the need for extra backend lookups. See our Item Catalog guide to learn how to mark fields as available for response enrichment.

Related Topics